POST/api/oidc/tokenPublic

Token endpoint

The OAuth 2.0 / OIDC token endpoint (RFC 6749 §3.2, form-encoded). Four grants: authorization_code (PKCE code_verifier required, redirect_uri must match; mints an id_token when the grant's scope includes openid), refresh_token (rotates the refresh token; the previous one is revoked), client_credentials (confidential clients only; mints a machine-to-machine access token for the app's service account, no refresh token), and RFC 8693 token exchange (urn:ietf:params:oauth:grant-type:token-exchange; confidential clients only: swaps a user's access token for an API server for a delegated access token on which the app's service account acts for that user (act claim), for the same API server, with at most the same scope; the API server must accept delegated tokens, else invalid_target; no refresh token). @schemavaults/auth-server extensions: the RFC 8707 resource parameter mints the access token for a registered API server, and refresh_token_delivery=http_only_cookie delivers the refresh token as an HTTP-only cookie (Set-Cookie) instead of in the body; every response with a refresh token carries refresh_token_expires_in. Browser callers (with an Origin header) must come from one of the client app's registered origins and then receive a credentialed CORS allowance; other callers get Access-Control-Allow-Origin: *. refresh_token, client_credentials and token exchange requests are rate limited per IP. Responses carry Cache-Control: no-store.

operationId post_api_oidc_tokenOpenID Connect / OAuth 2.0

Authentication & permissionsPublic

Anyone — no credentials required

Accepted credentials: None required
Notes: Client authentication per RFC 6749 §2.3: public clients send client_id only (PKCE is the security boundary); confidential clients (apps with a registered client secret) must authenticate with client_secret_basic (HTTP Basic Authorization header) or client_secret_post (client_secret form field). The handler performs this itself.

Request body

Required — Form-encoded token request. Which fields are required depends on grant_type.

application/x-www-form-urlencoded

OidcTokenRequest

Property	Type	Description
grant_type*	"authorization_code" \| "refresh_token" \| "client_credentials" \| "urn:ietf:params:oauth:grant-type:token-exchange"	Which grant to redeem.
client_id	string	The client application id. May be omitted when the client authenticates with `client_secret_basic` (the id then comes from the `Authorization` header). minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$
client_secret	string	`client_secret_post` authentication for confidential clients (apps with a registered client secret).
code	string	`authorization_code`: the code from the authorization response.
redirect_uri	string	`authorization_code`: must equal the `redirect_uri` of the authorization request.
code_verifier	string	`authorization_code`: the PKCE code verifier (RFC 7636).
refresh_token	string	`refresh_token`: the refresh token to rotate. Browser SDK clients that chose cookie delivery send it as the `refresh_token_<client_id>` cookie instead.
scope	string	`refresh_token`: requested scope, which may only narrow the originally granted scope. `client_credentials`: requested OIDC scopes (API scopes are not granted to service accounts). Token exchange: the delegated token's scope, which may only narrow the subject token's (default: the subject token's scope).
subject_token	string	Token exchange (RFC 8693): the access token a user holds for an API server, issued to this client. The delegated token is minted for the same user, client and API server. Token exchange only, like every RFC 8693 parameter (`subject_token_type`, `requested_token_type`, `actor_token`, `actor_token_type`): any other grant refuses a request carrying one with `invalid_request`. Conversely, a token exchange refuses the other grants' parameters (`code`, `code_verifier`, `redirect_uri`, `refresh_token`, `refresh_token_delivery`) with `invalid_request`.
subject_token_type	"urn:ietf:params:oauth:token-type:access_token"	Token exchange only: REQUIRED; only access tokens are exchanged.
requested_token_type	"urn:ietf:params:oauth:token-type:access_token"	Token exchange only: optional; only access tokens are issued.
resource	string	RFC 8707 resource indicator, as extended by @schemavaults/auth-server: the URL of a registered API server; the `access_token` is then minted for that audience instead of the reserved userinfo audience. At most one per request. The API scopes a grant holds (requested with that API server as the authorization request's `resource`) go on the access token only when it is minted for that API server. Token exchange: optional, and if sent it must equal the subject token's audience.
refresh_token_delivery	"inline" \| "http_only_cookie"	@schemavaults/auth-server extension: `http_only_cookie` sets the refresh token as the HTTP-only `refresh_token_<client_id>` cookie (plus a JS-readable expiry marker) and omits `refresh_token` from the body. Default `inline`.

Responses

Header	Type	Description
Cache-Control	string
Set-Cookie	string	Refresh token cookies when `refresh_token_delivery=http_only_cookie` was requested.

application/json

OidcTokenResponse

Property	Type	Description
access_token*	string	Encrypted (JWE) access token; opaque to the client.
token_type*	"Bearer"
expires_in*	integer	Access token lifetime in seconds.
refresh_token	string	Omitted for `client_credentials`, for token exchange, and when `refresh_token_delivery=http_only_cookie`.
refresh_token_expires_in	integer	@schemavaults/auth-server extension: seconds until the (possibly cookie-delivered) refresh token expires.
scope	string	Scope of the issued access token: the granted OIDC scopes, plus the grant's API scopes when the access token is minted for the API server that defines them. Omitted when it holds nothing (plain OAuth 2.1 grant).
id_token	string	RS256-signed id_token; only on an `authorization_code` grant whose scope includes `openid`.
issued_token_type	"urn:ietf:params:oauth:token-type:access_token"	Token exchange only (RFC 8693 §2.2.1): the type of the issued token.

JSONExample

"access_token""string"

"token_type""Bearer"

"expires_in"1

"refresh_token""string"

"refresh_token_expires_in"1

"scope""string"

"id_token""string"

"issued_token_type""urn:ietf:params:oauth:token-type:access_token"

Example request

bashcurl

curl -X POST 'https://auth.schemavaults.com/api/oidc/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=my-web-app' \
  --data-urlencode 'client_secret=string' \
  --data-urlencode 'code=string' \
  --data-urlencode 'redirect_uri=string' \
  --data-urlencode 'code_verifier=string' \
  --data-urlencode 'refresh_token=string' \
  --data-urlencode 'scope=string' \
  --data-urlencode 'subject_token=string' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'resource=https://api.example.com' \
  --data-urlencode 'refresh_token_delivery=inline'

Authentication & permissionsPublic

Request body

Responses

200The token response (RFC 6749 §5.1 / OIDC Core §3.1.3.3)

400OAuth error (invalid_request, unsupported_grant_type, invalid_grant, invalid_scope, invalid_target, unauthorized_client, ...), or the client IP could not be determined for rate limiting ({ success: false, message }).

401Client authentication failed (invalid_client)

403The request came from an origin the client application has not registered (invalid_request)

429Rate limited (refresh_token / client_credentials / token exchange grants)

500The token request could not be processed

Example request