> ## 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.

<AccordionGroup>
  <Accordion title="Missing grant_type" id="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>

  <Accordion title="Missing assertion" id="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>

  <Accordion title="Missing refresh_token" id="missing-refresh-token">
    `Missing required parameter: refresh_token`

    The `refresh_token` grant needs the prior refresh token in `refresh_token`.
  </Accordion>

  <Accordion title="Missing target" id="missing-target">
    `Missing target parameter`

    A launch must say where to land. Set `target` to an allowed app path. See [Targets](/guides/user-launch-flows#targets).
  </Accordion>

  <Accordion title="Invalid target" id="invalid-target">
    The launch `target` is not a relative path, or is not an allowed destination. Pass one of the allowed targets. See [Targets](/guides/user-launch-flows#targets). Absolute URLs and unknown paths are rejected so a launch can't be redirected off-site.
  </Accordion>

  <Accordion title="Invalid return_url" id="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>

  <Accordion title="Launch page is not embedded" id="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](/guides/jwt-authentication#launch-the-user-into-the-app) method instead.
  </Accordion>

  <Accordion title="Assertion is not a valid JWT" id="jwt-malformed">
    `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](/guides/jwt-authentication#sign-a-user-jwt).
  </Accordion>
</AccordionGroup>

## unsupported\_grant\_type

<AccordionGroup>
  <Accordion title="Unsupported grant_type" id="unsupported-grant-type">
    `Unsupported grant_type: <value>`

    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.
  </Accordion>
</AccordionGroup>

## invalid\_scope

<AccordionGroup>
  <Accordion title="Unknown scope" id="unknown-scope">
    `Unsupported scope: <value>`

    The JWT's `scope` claim contains a value Etherfuse doesn't recognize. Use a documented scope (see [Scopes](/guides/jwt-authentication#scopes)), or an empty string to provision a user with no abilities.
  </Accordion>

  <Accordion title="Scope not allowed for partner auth" id="scope-not-allowed">
    `Scopes not allowed for partner auth: <value>. (Valid: kyb)`

    The scope is recognized but not permitted for partner JWTs. Today the only grantable partner scope is `kyb`.
  </Accordion>
</AccordionGroup>

## invalid\_grant

The JWT or refresh token was rejected.

<AccordionGroup>
  <Accordion title="JWT has expired" id="jwt-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>

  <Accordion title="JWT audience mismatch" id="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>

  <Accordion title="Invalid replay-protection claim" id="jwt-replay">
    `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>

  <Accordion title="JWT missing email" id="jwt-missing-email">
    `JWT missing email claim`

    Include an `email` claim in the JWT.
  </Accordion>

  <Accordion title="JWT missing name" id="jwt-missing-name">
    `JWT missing or empty name claim`

    Include a non-empty `name` claim in the JWT.
  </Accordion>

  <Accordion title="Subject is a business organization" id="subject-business-org">
    `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>

  <Accordion title="Invalid or expired refresh token" id="invalid-refresh-token">
    `Invalid or expired refresh token`

    The refresh token is unknown or has expired. Sign a fresh JWT and exchange it again.
  </Accordion>

  <Accordion title="Unknown user" id="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](/guides/jwt-authentication).
  </Accordion>

  <Accordion title="Account deactivated" id="account-deactivated">
    `Account deactivated`

    This customer's Etherfuse account is deactivated and can't authenticate. Contact your Etherfuse representative.
  </Accordion>
</AccordionGroup>

## invalid\_client

<AccordionGroup>
  <Accordion title="Unknown issuer" id="unknown-issuer">
    `Unknown issuer: <iss>`

    The JWT's `iss` isn't registered with Etherfuse, 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](/guides/jwt-authentication#before-you-start).
  </Accordion>

  <Accordion title="Signature verification failed" id="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>

  <Accordion title="JWKS endpoint unreachable or invalid" id="jwks-unreachable">
    `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](/guides/jwt-authentication#before-you-start).
  </Accordion>

  <Accordion title="No response from partner" id="no-partner-response">
    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 via postMessage](/api-reference/launch-via-postmessage).
  </Accordion>
</AccordionGroup>

## server\_error

<AccordionGroup>
  <Accordion title="Auth provider misconfigured" id="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>

  <Accordion title="Server error" id="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`.
  </Accordion>
</AccordionGroup>