Refresh token
Get new access token using refresh token. The X-App-ID header must match the value used during authentication; a mismatch revokes the refresh token. The Authorization header must contain an authenticated access token (`sub=user_auth`); MFA challenge tokens are rejected.
In: header
Header Parameters
Application identifier. Must be a value from the configured whitelist (e.g. web-app, admin-app, configurator-app). When provided, the refresh token cookie is scoped per application to prevent cross-app token collisions. If a whitelist is configured and the value is not in it, the request is rejected with 400.
Device identifier for device binding.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/refresh-token"{
"access_token": "string",
"expires_in": 0,
"idle_timeout_seconds": 0,
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}{
"status": 400,
"code": "auth_m.invalid_app_id",
"message": "Invalid application identifier"
}{
"status": 401,
"code": "auth.invalid_access_token",
"message": "Invalid or expired token"
}Invalidate tokens and end session
Verify 2FA code and complete authentication. This is the only point where MFA-enabled logins receive authenticated session artifacts. When auth.2fa_challenge=true, send the challenge token from /v1/authenticate in X-MFA-Challenge. Failed codes are counted: a wrong code reports the attempts left, and once they are exhausted a cooling-off period starts and further attempts are refused until it elapses. Branch on `code` (`otp_m.otp_invalid`, `otp_m.max_attempts_reached`, `otp_m.cooling_period_active`) rather than on the status: the TOTP branch reports a wrong code as 400 (the web middleware treats 401 as a token-refresh signal) while the email/phone branch reports it as 401, and both branches keep 429 for the two rate-limited states so the client can read the time left. The cooling-off gate fails closed: a read the server cannot complete refuses the attempt with 500 `otp_m.cache_error` on both branches rather than letting it through.