POST/api/oidc/tokenPublic

Token endpoint

The OAuth 2.0 / OIDC token endpoint (RFC 6749 §3.2, form-encoded). Three 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), and client_credentials (confidential clients only; mints a machine-to-machine access token for the app's service account, 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 and client_credentials 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"	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` / `client_credentials`: requested scope, which may only narrow the originally granted scope.
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.
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` 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	Granted scope; omitted when nothing was granted (plain OAuth 2.1 grant).
id_token	string	RS256-signed id_token; only on an `authorization_code` grant whose scope includes `openid`.

JSONExample

"access_token""string"

"token_type""Bearer"

"expires_in"1

"refresh_token""string"

"refresh_token_expires_in"1

"scope""string"

"id_token""string"

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 '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 grants)

500The token request could not be processed

Example request