Exchange OIDC authorization code for a system JWT

POST

/v1/auth/callback

curl --request POST \
  --url https://example.com/v1/auth/callback \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "redirect_uri": "example", "state": "example" }'

Request Body ^required

Media type application/json

object

code

required

Authorization code received from the OIDC IdP.

string

redirect_uri

required

The redirect URI used in the original authorization request.

string

state

HMAC-signed state token from the per-tenant OIDC flow. When present, the server verifies it and uses per-tenant oidc_config. When absent, falls back to the global OIDC provider.

string

Example ^generated

{
  "code": "example",
  "redirect_uri": "example",
  "state": "example"
}

Responses

200

Successful exchange. Returns a signed system JWT.

Media type application/json

object

token

required

System-issued JWT for use in subsequent Bearer-authenticated requests.

string

expires_at

required

UTC timestamp when the token expires.

string format: date-time

Example ^generated

{
  "token": "example",
  "expires_at": "2026-04-15T12:00:00Z"
}

401

Invalid or expired authorization code.

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}