Documentation/Developers
Back
  • Getting started
    • Frontends and app types
    • Environments and endpoints
  • OAuth clients
    • Client ID and secret
    • Redirect URIs and start URL
    • Secret rotation
  • Login with appsolut
    • Authorization code flow
    • Tokens and claims
    • Frontend role
    • Sign-out
    • Revocation and issued tokens
    • Token endpoint errors
  • Frontend keys
    • Issue and store a key
    • Send a key
    • Rotate and revoke
  • Members API
    • Eligibility from a backend
    • The signed-in member
    • Results, rate limits and errors
    • Is an applicant an eligible member?
    • The signed-in frontend user's membership
  • appsolut register API
    • Implement the API
    • Connect and test
    • Verify a member with their challenge code
    • List every member
    • The status of several members
    • The status of one member
    • The person data of several members
    • The person data of one member
    • The claims of several members
    • The claims of one member
    • Health check

Token endpoint errors

The answers a code exchange or a refresh can get, and what to do with each.

POST <auth>/oauth/token answers errors in two formats. Read the status and handle both bodies.

RFC 6749 errors

HTTP 400 with a body like:

{ "error": "invalid_grant", "error_description": "Authorization code has expired" }

These are code exchange problems: an expired, used or unknown code, a wrong code_verifier or redirect_uri (invalid_grant); a missing parameter (invalid_request); a user blocked meanwhile (access_denied).

The Auth server's own errors

A body like {"code": 400, "error_code": "...", "msg": "..."}, as long as you send no X-Supabase-Api-Version header (with one, it becomes {"code": "<error_code>", "message": "..."}):

  • Client authentication fails: 400, error_code invalid_credentials. A wrong or rotated secret, or the secret not sent as HTTP Basic.
  • A refresh token that no longer works: 400, error_code refresh_token_not_found (the session was ended), refresh_token_already_used (reused after 10 seconds; the session is ended now), user_banned, session_not_found or session_expired. Treat every one as signed out.
  • The token was refused: 403, error_code unknown, with the reason in msg. These come at the code exchange and at a refresh alike.

The 403s a frontend can meet

msgWhenWhat to do
The frontend is for members onlyMembership mandatory, and the user is not a member now.Drop the session and send the user through sign-in again.
OAuth tokens are issued for the scope openid onlyThe authorize request's scope was not exactly openid (none at all included).Fix the authorize request; it is a bug in your frontend.
The OAuth client is not an internal web frontendYour client's frontend is not an internal frontend with the app type "Web app".Drop the session; ask the organisation to check the frontend's "Sign-in" card.
The OAuth client does not serve the frontend user's tenantYour client ID is not (or no longer) a frontend of the user's organisation, for example after the client was recreated.Check the client ID and secret you deploy against the "Sign-in" card, then send the user through sign-in again.
The access token could not be issuedThe token could not be computed (an internal error).Treat as signed out; retry later, and report the time to appsolut if it repeats.
Any other msgAccount or session states that no regular sign-in produces.Treat as signed out, and report the msg and the time to appsolut.