Skip to content

Insufficient Authorization

URI: https://docs.ankatech.co/errors/insufficient_authorization
HTTP Status: 403 Forbidden

The type suffix uses the underscore form of the OAuth 2.0 error code insufficient_authorization it accompanies, so the two identifiers match. The OAuth 2.0 for First-Party Applications draft (draft-ietf-oauth-first-party-apps) defines the code for its authorization challenge endpoint, and lets the token endpoint answer a token request, a refresh included, with the same challenge.

When you see this

A refresh_token grant at the token endpoint (POST /api/v3/auth/token, operation createToken) needs the person to authenticate further before a token can be issued. It happens in two cases:

  • The grant carries tenant_id to switch into another tenant, and that tenant's authentication posture requires more than the evidence the session was authenticated with (for example, the tenant admits passkeys only and the session signed in with a password and a TOTP code).
  • The grant carries max_age, and the session's most recent authentication for its tenant is older than that.

Nothing is issued or rotated, and the presented refresh token stays usable for its own tenant. The answer carries an auth_session: a single-use value bound to the session and the tenant, with which the client continues the step at POST /api/v3/auth/authorize-challenge (operation submitAuthorizationChallenge). The response carries Cache-Control: no-store.

A switch into a tenant in which the identity holds no ACTIVE, admitted membership is the 400 Invalid Grant of every refused switch, never this answer.

The authorization challenge endpoint answers the next step of a sign-in with its own 403 carrying error: insufficient_authorization, an auth_session and the step to take. That body has no type and is not this problem: it is the sign-in continuing, not a refused token request.

Common Causes

  • A tenant switch into a tenant whose authentication policy requires a passkey or an approved identity provider, from a session that signed in with a password.
  • A refresh that asks for a recent authentication (max_age) from a session that signed in earlier than that.

Response Example

{
  "error": "insufficient_authorization",
  "error_description": "The requested tenant requires further authentication. Continue at the authorization challenge endpoint with this auth_session and a new S256 code_challenge.",
  "error_uri": "https://docs.ankatech.co/errors/insufficient_authorization",
  "type": "https://docs.ankatech.co/errors/insufficient_authorization",
  "title": "Insufficient Authorization",
  "status": 403,
  "detail": "The requested tenant requires further authentication. Continue at the authorization challenge endpoint with this auth_session and a new S256 code_challenge.",
  "instance": "/api/v3/auth/token",
  "timestamp": 1763112600,
  "auth_session": "jT4Wq7Zp2Lk9Rv1Xc6Bn3Md8Fs5Gh0Yu2Ei7Oa4Tw9"
}

For the max_age case, error_description and detail read: "The session's most recent authentication is older than max_age. Continue at the authorization challenge endpoint with this auth_session and a new S256 code_challenge."

Content-Type: application/json — the RFC 6749 §5.2 error shape of the token endpoint, with the RFC 9457 members alongside. The Auth API carries no correlation member in the body: correlate through the X-Correlation-Id response header. See Error Index & Overview.

How to Resolve

  1. Keep the auth_session from the answer. Do not cache or log it: it is single use.
  2. Continue at POST /api/v3/auth/authorize-challenge with that auth_session, a new S256 code_challenge and no action, and complete the authentication step it asks for.
  3. The refresh token you presented is unchanged and still valid for its own tenant.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.