Session elevation
POST /v1/auth/elevation and /elevation/complete — two-step recent authentication (RFC 9470).
Elevation is "prove, inside the existing session, that it is you right now". It satisfies the max_age requirement of destructive operations. It differs from signing in again in that the session stays the same; only the authentication time is moved to the present.
Endpoints
| Method | Path | Credential | Purpose |
|---|---|---|---|
POST | /v1/auth/elevation | Session token | Start the flow; returns a flow token and available methods |
POST | /v1/auth/elevation/complete | Flow token (JWE) | Finish the flow; re-sign the access token |
Step one: start
| Parameter | Type | Required | Notes |
|---|---|---|---|
acr_values | string | Optional | Target strength; when several are listed, the highest applies |
{
"success": true,
"flow_token": "eyJ...",
"required_acr": "urn:muoceon:acr:aal2",
"available_methods": [
{ "type": "passkey", "remaining": 1 },
{ "type": "authenticator", "remaining": 1 }
]
}required_acr is the target level for this flow; available_methods are the methods this account can use right now.
Step one is not elevated
It is the entry point to elevation. Requiring recent authentication here would trap the user in "to elevate, first elevate".
Middle steps
Use the returned flow_token with the /verify/* endpoints in Verification challenges; every step hands back a new flow token.
Step two: complete
The Bearer header carries the flow token (not the session token), and there is no request body.
{
"success": true,
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 900,
"acr": "urn:muoceon:acr:aal2",
"auth_time": "2026-11-14T09:02:41.000Z"
}| Result | Notes |
|---|---|
| Target met | The session's auth_time moves to now and the access token is re-signed; the refresh token is not rotated |
| Target not met | 401 with an RFC 9470 WWW-Authenticate challenge; the flow token stays valid and a stronger method can be retried |
Typical usage
- Call a destructive endpoint and receive
401withWWW-Authenticate; - call
POST /elevationand render the UI fromavailable_methods; - after completing the verification challenge, call
/elevation/complete; - replay the original request with the new access token.
Related
- Which endpoints require step-up: auth context overview
- Background on the design: Recent authentication