Skip to main content
POST
SDK — exchangeToken()
POST /v1/auth/token Exchange a long-lived service key for a short-lived GatelitSigned token. The gateway verifies the service key, signs a token with its internal secret, and returns it. No raw signing secret is ever exposed to your backend. Use this to issue per-user tokens from your backend — authenticate with a service key, provide the user’s identity and optional constraints, and receive a token your frontend can use directly with any other gateway endpoint.

Auth

Only service keys are accepted at this endpoint. Signed tokens and OIDC are rejected.

Request body

The issued token inherits the orgId from the service key used to authenticate the exchange. This enables org-scoped provider key resolution for the downstream requests.

Response

Use the returned token with the GatelitSigned scheme on all other gateway endpoints:

Examples

curl — minimal

curl — with model constraint and token cap

SDK — exchangeToken()

Errors

Authorizations

Authorization
string
header
required

Long-lived service key for backend-to-backend use. Format: GatelitKey glk_...

Create service keys in the dashboard under Settings → Service Keys.

Body

application/json
sub
string
required

Subject identifier — typically the end user's ID.

ttl
integer
default:60

Token lifetime in seconds (max 1 hour).

Required range: 1 <= x <= 3600
model
string

Restrict to one model in provider/model format.

maxTokens
integer

Cap output tokens per request.

endUserId
string

End-user identifier for log filtering.

requestSource
enum<string>
default:api
Available options:
api,
eval

Response

Signed token issued successfully.

token
string

The signed token for use with GatelitSigned auth.

scheme
enum<string>
Available options:
GatelitSigned