The Gatekeeper HTTP API is a single Hono app (apps/api/src/index.ts). Two public routes sit at the root and every functional resource lives under a versioned /v1 sub-app. The SDKs are thin transports over this surface, so the route table below is the contract the clients call.
On success the SDK core unwraps { ok, data } and returns data directly. On ok !== true or a non-2xx status it throws a GatekeeperError carrying the status, error message, machine code, and any Retry-After. See the errors reference.
Two routes bypass the envelope and return raw bodies:
GET /v1/audit/export returns application/x-ndjson (default) or text/csv.
GET /v1/.well-known/jwks.json returns a JWKS object.
The root app.notFound and app.onError return { ok: false, error } without a code at 404 / 500 respectively.
List endpoints accept limit and cursor query params. limit is a positive integer clamped to a maximum of 100; absent or invalid values fall back to 50. The response carries data.nextCursor (an opaque string, or null when there is no further page). Several list endpoints (GET /v1/tenants, members, roles, plans, provider-configs, webhook endpoints) return the full set with nextCursor: null to keep the list envelope uniform.
Credentials arrive in the Authorization header (or, for a few public routes, in the request body or as a provider signature). Each credential resolves to an actor kind. Full detail is in the authentication reference.
Credential
Header / source
Actor kind
Used on
User JWT
Authorization: Bearer <jwt>
user
tenant routes
API key
request body field (/keys/validate, /keys/token)
apiKey (tenant-bound, scoped)
key validate / token
Platform key (gkp_)
Authorization: Bearer <key>
platform (service account)
platform routes
Bootstrap token
Authorization: Bearer <token>
platformBootstrap
platform management only
none
(absent)
anonymous
public / pre-auth
Each protected handler runs the same pipeline: parse and validate input, call guard() with an AccessPolicy, then on allow delegate to a domain service and wrap the result in the envelope. The policy kinds a route can require:
Policy kind
Meaning
authenticated
any valid user bearer token
tenantMember
caller is a member of the named tenant
tenantManage
caller is owner/admin of the named tenant
tenantSelfOrManage
caller is the targetUserId, or can manage the tenant
platformPermission
platform credential holds a platform permission (optionally requireServiceAccount)
public
no identity (used only by the rate-limit pre-check)
hideNotFound: true remaps a NOT_A_MEMBER 403 deny to a 404 so non-members cannot probe resource existence.
All paths include the /v1 prefix. The Auth column is the guard policy unless the route is marked public. Rate-limited public routes run enforceRateLimit() before any work and set Retry-After on a 429.
All platform routes authenticate a platform credential (bootstrap token or gkp_ key) and require a platformPermission. Operational routes set requireServiceAccount: true, which rejects the bootstrap token and forces a real service account. Each route also enforces its own platform rate-limit bucket.
Method
Path
Auth / policy
Purpose
POST
/v1/platform/service-accounts
platformPermissionservice_accounts:write
Create a service account (delegation gated by the operator's own permissions) (201).
GET
/v1/platform/service-accounts
platformPermissionservice_accounts:write
List service accounts (non-bootstrap actors see only ones they can manage).