> ## Documentation Index > Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Authentication errors > What each JWT auth and launch error means, and how to fix it. Authentication failures follow the OAuth 2.0 error format ([RFC 6749 §5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)): ```json theme={null} { "error": "invalid_scope", "error_description": "Scopes not allowed for partner auth: foo. (Valid: kyb)", "error_uri": "https://docs.etherfuse.com/guides/authentication-errors#scope-not-allowed" } ``` * **`error`** is the machine-readable category (one of the headings below). * **`error_description`** is a human-readable detail. * **`error_uri`** links straight to the matching entry on this page, which opens automatically. Find your error by its `error` code below. ## invalid\_request The request was missing a parameter or had a malformed value. > [accordion] Missing grant\_type > > `Missing required parameter: grant_type` > > Every request needs a `grant_type` of `urn:ietf:params:oauth:grant-type:jwt-bearer` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)) or `refresh_token` ([RFC 6749 §6](https://www.rfc-editor.org/rfc/rfc6749#section-6)). > [accordion] Missing assertion > > `Missing required parameter: assertion` > > The `jwt-bearer` grant needs the signed JWT in `assertion`. (A launch may instead send a `refresh_token`.) > [accordion] Missing refresh\_token > > `Missing required parameter: refresh_token` > > The `refresh_token` grant needs the prior refresh token in `refresh_token`. > [accordion] Missing target > > `Missing target parameter` > > A launch must say where to land. Set `target` to an allowed app path. See [Targets](https://docs.etherfuse.com/v2/guides/user-launch-flows.md#targets). > [accordion] Invalid target > > The launch `target` is not a relative path, or is not an allowed destination. Pass one of the allowed targets. See [Targets](https://docs.etherfuse.com/v2/guides/user-launch-flows.md#targets). Absolute URLs and unknown paths are rejected so a launch can't be redirected off-site. > [accordion] Invalid return\_url > > The launch `return_url` is not a valid `http(s)` URL. Pass an absolute `https://` URL, or omit it entirely: `return_url` is optional. > [accordion] Launch page is not embedded > > A `postMessage` launch was opened without a parent or opener to request credentials from. Open the launch page in an iframe or a popup so it can ask your page for the JWT, or use the [form POST](https://docs.etherfuse.com/v2/guides/jwt-authentication.md#launch-the-user-into-the-app) method instead. > [accordion] Assertion is not a valid JWT > > `Assertion is not a valid JWT` > > The `assertion` couldn't be parsed as a JWT. Check that you're sending the compact-serialized token (three base64url segments separated by dots), not a decoded payload. See [Sign a user JWT](https://docs.etherfuse.com/v2/guides/jwt-authentication.md#sign-a-user-jwt). ## unsupported\_grant\_type > [accordion] Unsupported grant\_type > > `Unsupported grant_type: ` > > Use `urn:ietf:params:oauth:grant-type:jwt-bearer` ([RFC 7523](https://www.rfc-editor.org/rfc/rfc7523), exchange a JWT) or `refresh_token` ([RFC 6749 §6](https://www.rfc-editor.org/rfc/rfc6749#section-6), refresh a session). No other grant types are supported. ## invalid\_scope > [accordion] Unknown scope > > `Unsupported scope: ` > > The JWT's `scope` claim contains a value Etherfuse doesn't recognize. Use a documented scope (see [Scopes](https://docs.etherfuse.com/v2/guides/jwt-authentication.md#scopes)), or an empty string to provision a user with no abilities. > [accordion] Scope not allowed for partner auth > > `Scopes not allowed for partner auth: . (Valid: kyb)` > > The scope is recognized but not permitted for partner JWTs. Today the only grantable partner scope is `kyb`. ## invalid\_grant The JWT or refresh token was rejected. > [accordion] JWT has expired > > `JWT has expired` > > The token's `exp` is in the past. Sign short-lived tokens and exchange them promptly. Check for clock skew between your signer and real time. > [accordion] JWT audience mismatch > > `JWT audience mismatch` > > The `aud` claim isn't the token endpoint. Set `aud` to `https://api.etherfuse.com/auth/token` (or the sandbox host `https://api.sand.etherfuse.com/auth/token`). > [accordion] Invalid replay-protection claim > > `JWT nonce or jti has already been used` / `JWT must include a unique nonce or jti claim` / `JWT nonce and jti claims must not differ` > > Each JWT must carry a unique replay-protection value in a `jti` (JWT ID) or `nonce` (OIDC) claim, and a given value can be exchanged only once. Generate a fresh one for every token. Send at least one of the two; if you send both, they must be identical. > [accordion] JWT missing email > > `JWT missing email claim` > > Include an `email` claim in the JWT. > [accordion] JWT missing name > > `JWT missing or empty name claim` > > Include a non-empty `name` claim in the JWT. > [accordion] Subject is a business organization > > `Subject must not be a business organization id` > > The `sub` names a business organization. It must be a customer's UUID, not the id of a business org. > [accordion] Invalid or expired refresh token > > `Invalid or expired refresh token` > > The refresh token is unknown or has expired. Sign a fresh JWT and exchange it again. > [accordion] Unknown user > > `Unknown user` > > The session's user no longer exists (for example, the account was removed). Sign a fresh JWT and exchange it again to re-establish the user. See [JWT User Authentication](https://docs.etherfuse.com/v2/guides/jwt-authentication.md). > [accordion] Account deactivated > > `Account deactivated` > > This customer's Etherfuse account is deactivated and can't authenticate. Contact your Etherfuse representative. ## invalid\_client > [accordion] Unknown issuer > > `Unauthorized` > > The JWT's `iss` isn't a registered issuer URL, so we can't find your JWKS. Confirm `iss` matches exactly what you registered, and contact your Etherfuse representative if it hasn't been set up yet. See [Before you start](https://docs.etherfuse.com/v2/guides/jwt-authentication.md#before-you-start). > [accordion] Signature verification failed > > `JWT signature verification failed` > > The signature didn't validate against the keys in your JWKS. Confirm the token is signed by a key published in your JWKS and that its `kid` header matches that key. If you rotated keys, make sure the new public key is live at your JWKS URL. > [accordion] JWKS endpoint unreachable or invalid > > `JWKS endpoint unreachable` / `JWKS bad response` > > We couldn't fetch a valid JWKS from **your** endpoint, so the signature can't be verified (returns `502`/`504`). Make sure your JWKS URL is publicly reachable over HTTPS and returns a valid JSON Web Key Set. See [Before you start](https://docs.etherfuse.com/v2/guides/jwt-authentication.md#before-you-start). > [accordion] No response from partner > > A `postMessage` launch asked your page for credentials and timed out. Respond to `etherfuse:auth:request` promptly, or send `etherfuse:auth:await` first if you need a moment to sign a JWT. See [Launch a user via postMessage](https://docs.etherfuse.com/v2/api-reference/authentication/launch-a-user-via-postmessage.md). ## server\_error > [accordion] Auth provider misconfigured > > The auth provider Etherfuse set up for your issuer is incomplete or invalid (a missing or malformed JWKS/issuer URL, or no organization linked). You can't fix this one yourself. Contact your Etherfuse representative so we can correct the configuration. > [accordion] Server error > > Something failed on Etherfuse's side while creating the session (for example, issuing the token). These are transient. Retry, and if it persists, contact your Etherfuse representative with the `error_description`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.