POST /api/v1/session/oidc

OpenID Connect sign-in, step 5: redeem the sign-in with a mint proof; receive a sender-constrained bearer session.

Redeems a verified sign-in ONCE and returns a session acting as the mapped XAuth principal, minted by the key server through this Gateway's delegator (AM04, the same verified TLS as every other path) and bound to the page key: every request on it needs a DPoP proof signed by that key. No cookie carries it, and no key-server token is returned. The session is published only after every part of its issuance committed and is unwound in reverse otherwise.

The request carries the mint proof in the TE-SSO-Mint header: a compact ES256 JWS with header {alg: "ES256", typ: "te-sso-mint+jwt", jwk: <the page's public JWK>} and claims mth: "oidc", org (this Gateway's public origin, exactly), htm: "POST", nonce (step 4's), flow (the flowId), iat (within 30 s), jti (unique) and bth (base64url SHA-256 of the exact request body bytes). It is not a DPoP proof.

The session ends at expiresAt (the earlier of the ID token's expiry and the binding's session lifetime), when idle past the binding's idle bound (401 SSO_SESSION_EXPIRED), at DELETE /api/v1/session, or when an operator ends its binding or mapping.

Authentication

No session required. This operation is reachable without an Authorization header. See Authenticating.

Parameters

Name	In	Required	Type	Description
TE-SSO-Mint	header	yes	string	The mint proof.

Request

Field	Type	Required	Description
flowId	string	yes
redemptionSecret	string	yes
signingJwk	object	yes	The page's public JWK -- the one step 1 named.

Example

{
  "flowId": "...",
  "redemptionSecret": "...",
  "signingJwk": {}
}

Responses

200

A sender-constrained session.

Field	Type	Required	Description
session	string	yes	The bearer credential.
actingAs	string	yes	The XAuth principal the session acts as.
expiresAt	string	yes
jkt	string	yes	The RFC 7638 thumbprint of the page key.
method	string (oidc)	yes
detail	string	yes

Example

{
  "session": "...",
  "actingAs": "...",
  "expiresAt": "...",
  "jkt": "...",
  "method": "oidc",
  "detail": "..."
}

400

OIDC_REQUEST_MALFORMED, MINT_PROOF_MISSING, MINT_PROOF_MALFORMED, or DELEGATION_UNSUPPORTED.

401

TRANSACTION_UNKNOWN -- the sign-in is unknown, already redeemed, expired, or the secret or the nonce is wrong. MINT_PROOF_KEY_MISMATCH -- the key redeeming is not the one step 1 named. MINT_PROOF_ALG, MINT_PROOF_SIGNATURE, MINT_PROOF_BINDING (a claim does not match this redemption), MINT_PROOF_CLOCK, MINT_PROOF_REPLAYED, METHOD_MISMATCH, GRANT_CONSUMED, GRANT_EXPIRED. None of them names a token.

403

IDENTITY_NOT_MAPPED -- the mapping was disabled or removed since the callback. BINDING_REVOKED -- the binding was disabled or changed during the sign-in. KS_SYSTEM_MISMATCH -- the mapping names another key server. ILLEGAL_GRANT. And the key server's delegation refusals, relayed as on POST /api/v1/session/delegated: DELEGATOR_NOT_PERMITTED, DELEGATOR_TOO_NARROW, TARGET_DISABLED.

404

TARGET_NOT_FOUND -- the mapped XAuth principal does not exist on the key server.

413

PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.

429

RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.

500

A fault rather than a refusal.

OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.

503

SSO_CAPACITY (Retry-After) -- the session store or the sender index is full; nothing was sent to the key server. DELEGATION_NOT_CONFIGURED -- this Gateway holds no delegator identity. SSO_ISSUE_FAILED -- an issuance stage failed for a reason no other code names; everything it had done was undone. OIDC_NOT_CONFIGURED, SESSION_LIMIT, CAPACITY_UNAVAILABLE.

Error handling

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

Status	Meaning
400	OIDC_REQUEST_MALFORMED, MINT_PROOF_MISSING, MINT_PROOF_MALFORMED, or DELEGATION_UNSUPPORTED.
401	TRANSACTION_UNKNOWN -- the sign-in is unknown, already redeemed, expired, or the secret or the nonce is wrong. MINT_PROOF_KEY_MISMATCH -- the key redeeming is not the one step 1 named. MINT_PROOF_ALG, MINT_PROOF_SIGNATURE, MINT_PROOF_BINDING (a claim does not match this redemption), MINT_PROOF_CLOCK, MINT_PROOF_REPLAYED, METHOD_MISMATCH, GRANT_CONSUMED, GRANT_EXPIRED. None of them names a token.
403	IDENTITY_NOT_MAPPED -- the mapping was disabled or removed since the callback. BINDING_REVOKED -- the binding was disabled or changed during the sign-in. KS_SYSTEM_MISMATCH -- the mapping names another key server. ILLEGAL_GRANT. And the key server's delegation refusals, relayed as on POST /api/v1/session/delegated: DELEGATOR_NOT_PERMITTED, DELEGATOR_TOO_NARROW, TARGET_DISABLED.
404	TARGET_NOT_FOUND -- the mapped XAuth principal does not exist on the key server.
413	PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.
429	RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.
500	A fault rather than a refusal. OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.
503	SSO_CAPACITY (Retry-After) -- the session store or the sender index is full; nothing was sent to the key server. DELEGATION_NOT_CONFIGURED -- this Gateway holds no delegator identity. SSO_ISSUE_FAILED -- an issuance stage failed for a reason no other code names; everything it had done was undone. OIDC_NOT_CONFIGURED, SESSION_LIMIT, CAPACITY_UNAVAILABLE.