Put a service behind the gateway

Before you start#

Steps#

1. Write the route#

A route is one entry in the routes list of the route table. Pick an id (lowercase kebab-case, unique, at most 63 characters): Access receives it as routeId, so grants and logs name your service by it.

{
  "id": "reports-api",
  "match": { "host": "api.example.com", "path": "/reports/{workspaceId}/" },
  "upstream": "http://reports.internal:3000",
  "auth": { "mode": "any", "workspace": { "param": "workspaceId", "requireUuid": true } },
  "forwardAuthorization": false
}

Decide each part on purpose:

The gateway refuses an unknown key, a route that is ambiguous with another, and accessCheck on a none route, so mistakes show up at validation rather than in traffic (gateway spec §3.2).

2. Validate and publish the table#

The gateway always replaces the whole table, never one route. Start from the active table, add your route to its routes list, and save the result as routes.json.

With the CLI (PLATFORMCTL_CONTROL_TOKEN holds the token):

platformctl routes get                      # active revision and table
platformctl routes validate ./routes.json   # errors, conflicts, warnings, diff; writes nothing
platformctl routes apply ./routes.json      # new revision, compare-and-swap on the active one
platformctl routes replicas                 # every replica should report the new revision

Over HTTP, against the control plane's internal address:

CONTROL=http://127.0.0.1:9090
curl -s -H "Authorization: Bearer $TOKEN" $CONTROL/v1/config | jq '.revision'
curl -s -H "Authorization: Bearer $TOKEN" --data-binary @routes.json $CONTROL/v1/config/validate
curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H 'If-Match: "41"' \
  --data-binary @routes.json $CONTROL/v1/config
curl -s -H "Authorization: Bearer $TOKEN" $CONTROL/v1/replicas

A 409 means the table moved since you read it, or you touched a protected route: read it again and reapply your change. The full procedure, with rollback, is in Gateway operations: changing the route table.

A deployment that keeps routes in a file (GATEWAY_CONFIG_SOURCE=file) has no control plane write: edit the GATEWAY_CONFIG file instead, and the gateway reloads it atomically (gateway spec §12.3).

Read the warnings the validation and the running-policy log report for your route, such as authorization_forwarded or no_workspace_check. Each one names a permissive setting you should be able to justify (gateway spec §12.2).

3. Give your service the public key#

Get the public half of the deployment key from whoever runs the gateway, and load it into your service's configuration:

bun run identity:key --public

Your service only ever holds this public key. It never needs the private key or the session secret, and a public key cannot sign an identity (Upstream identity: key).

4. Verify the signed identity on every request#

The gateway removes any x-gateway-* header a client sent and writes its own: x-gateway-user, x-gateway-email, x-gateway-roles, x-gateway-workspace and x-gateway-signature (Upstream identity: headers). Your service must check the signature before it reads any of them.

The quickest correct path is to copy the standalone reference verifier, examples/upstream-identity/verify.ts, whose only import is jose, and call it from your request handler:

const result = await verifyIdentity({ request, headers, publicKey: key })
if (!result.ok) {
  log.warn({ reason: result.reason }, 'identity refused')
  return new Response('forbidden', { status: 403 })
}

The complete TypeScript and Go examples are in Upstream identity: code. Three inputs trip up most implementations:

A mode: none route forwards requests with no identity and no signature, so decide per route whether your service accepts them (Upstream identity: failed verification).

The roles in x-gateway-roles come from the caller's token, which was issued at login. If your service needs the caller's current permissions, it can read them from Access's context contract with a credential of its own, as Data does (Access API: access context).

5. Test the verifier against the gateway's signer#

The reference verifier ships with verify.test.ts, which signs with the gateway's real signer. Run the same kind of test against your own implementation, and pin the gateway revision you test against (Upstream identity: compatibility).

6. Grant callers access in Access#

The gateway asks Access whether the caller's principal may use the workspace on route reports-api. A grant answers yes when its workspace and route match or are left empty (null covers every workspace or every route). The permission key is up to you, as long as it is enabled (Access spec §8.3).

platformctl access grants put --tenant acme --user-id <principal id> \
  --permission reports.read \
  --workspace-id 11111111-1111-4111-8111-111111111111 --route-id reports-api

The same grant over HTTP:

curl -sS -X PUT https://access.example.com/v1/admin/grants \
  -H "authorization: Bearer $ACCESS_ADMIN_TOKEN" -H "content-type: application/json" \
  -d '{"tenant":"acme","userId":"<principal id>","permission":"reports.read",
       "workspaceId":"11111111-1111-4111-8111-111111111111","routeId":"reports-api"}'

In the console, an operator does the same on the tenant's Rights page (console user guide). Grants to groups, roles and expiry dates are covered in Manage access and the Access API.

Check that it worked#

1. Put your route's decision to Access before any traffic arrives. A denial ends with exit status 6:

   platformctl access decide --subject <principal id> \
     --workspace 11111111-1111-4111-8111-111111111111 --route reports-api

1. Sign in through the gateway with a redirect to your route, for example https://api.example.com/auth/login?redirect=/reports/11111111-1111-4111-8111-111111111111/, then call it again with the session cookie:

   curl -s -i "https://api.example.com/reports/11111111-1111-4111-8111-111111111111/summary" \
     -H "cookie: gateway_session=<value from the browser>"

1. Your service's log should show a verified identity whose subject is the principal id. The gateway's log line for the response's x-request-id names route reports-api, the subject and the workspace (gateway spec §12.2).
2. Try the refusals on purpose. A principal without a grant gets 403 workspace_forbidden from the gateway. A request sent straight to your service's address, without the gateway, must get your own 403.
3. On /metrics, gateway_requests_total{route="reports-api"} counts your traffic and gateway_upstream_failures_total stays flat (gateway spec §12.1).

If something goes wrong#

Related#

• Upstream identity
• Gateway specification
• Gateway configuration
• Gateway operations
• CLI usage
• Manage access
• Build an app on Data
• Troubleshoot a request