Skip to main content
Authentication failures follow the OAuth 2.0 error format (RFC 6749 §5.2): 
{
  "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.
Missing required parameter: grant_typeEvery request needs a grant_type of urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523) or refresh_token (RFC 6749 §6).
Missing required parameter: assertionThe jwt-bearer grant needs the signed JWT in assertion. (A launch may instead send a refresh_token.)
Missing required parameter: refresh_tokenThe refresh_token grant needs the prior refresh token in refresh_token.
Missing target parameterA launch must say where to land. Set target to an allowed app path, e.g. /kyb.
The launch target is not a relative path, or is not an allowed destination. Pass one of the allowed targets (see Launch a user into the app); today that’s /kyb, optionally with ?org=<org_id>. Absolute URLs and unknown paths are rejected so a launch can’t be redirected off-site.
The launch return_url is not a valid http(s) URL. Pass an absolute https:// URL, or omit it entirely: return_url is optional.
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 method instead.
Assertion is not a valid JWTThe 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.

​
unsupported_grant_type

Unsupported grant_type: <value>Use urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523, exchange a JWT) or refresh_token (RFC 6749 §6, refresh a session). No other grant types are supported.

​
invalid_scope

Unsupported scope: <value>The JWT’s scope claim contains a value Etherfuse doesn’t recognize. Use a documented scope (see Scopes), or an empty string to provision a user with no abilities.
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.

​
invalid_grant

The JWT or refresh token was rejected.
JWT has expiredThe 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.
JWT audience mismatchThe 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).
JWT nonce has already been used / JWT must include a random nonce claimEach JWT must carry a unique nonce claim, and a nonce can be exchanged only once (replay protection). Generate a fresh nonce for every token.
JWT missing email claimInclude an email claim in the JWT.
JWT missing or empty name claimInclude a non-empty name claim in the JWT.
Subject must not be a business organization idThe sub names a business organization. It must be a customer’s UUID, not the id of a business org.
Invalid or expired refresh tokenThe refresh token is unknown or has expired. Sign a fresh JWT and exchange it again.
Unknown userThe 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.
Account deactivatedThis customer’s Etherfuse account is deactivated and can’t authenticate. Contact your Etherfuse representative.

​
invalid_client

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.
JWT signature verification failedThe 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.
JWKS endpoint unreachable / JWKS bad responseWe 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.
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.

​
server_error

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