Exchange a partner JWT

curl --request POST \
  --url https://api.etherfuse.com/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6Imt...

{
  "access_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<string>",
  "scope": "<string>"
}

User Authentication

Exchange a partner JWT

OAuth 2.0 token endpoint (RFC 6749 §3.2). Exchanges a partner-signed JWT for an Etherfuse access/refresh token pair, or refreshes an existing session.

Call this from your backend to provision a user ahead of a launch, or to prefetch a refresh_token that speeds up the launch redirect. Your backend signs a JWT with the key behind your registered JWKS and posts it here. To drop a user straight into the app in a browser, use POST /auth/launch instead.

Grant types

urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523). Put the partner JWT in assertion.
refresh_token (RFC 6749 §6). Put a prior refresh_token in refresh_token.

The JWT

Sign it with the key behind your registered JWKS (see Sign a user JWT for full detail). Claims:

iss: your registered issuer.
sub: the person signing in; a UUID is strongly recommended (for an individual customer it’s the same value as customerId in the Ramp API). Must name a person, never a business: a business org id is rejected with invalid_grant, and a sub can’t be reused as a business org id (POST /ramp/organization returns 409). A non-UUID sub still signs in, but can’t be addressed through the Ramp API.
aud: the token endpoint URL, https://api.etherfuse.com/auth/token (https://api.sand.etherfuse.com/auth/token in sandbox).
scope: required. Use kyb; an unrecognized scope is rejected with invalid_scope.
nonce: a fresh random value, unique per token (replay-protected).
exp, iat: required; keep tokens short-lived.
email, name: required; populate the user’s profile. picture is optional.

This endpoint is unauthenticated: the signed JWT (or refresh token) is the credential. Do not send an API key.

POST

auth

token

Exchange a partner JWT

curl --request POST \
  --url https://api.etherfuse.com/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6Imt...

{
  "access_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<string>",
  "scope": "<string>"
}

Body

grant_type

enum<string>

required

The OAuth 2.0 grant type.

Available options:

urn:ietf:params:oauth:grant-type:jwt-bearer,

refresh_token

assertion

string

The partner-signed JWT. Required when grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer.

refresh_token

string

A refresh token from a prior exchange. Required when grant_type is refresh_token.

Response

A bearer access token and refresh token

access_token

string

required

Bearer token for the Ramp API. Send it as Authorization: Bearer <access_token>.

token_type

string

required

Example:

"Bearer"

expires_in

integer

required

Access token lifetime, in seconds.

Example:

3600

refresh_token

string

required

Use with the refresh_token grant to obtain a fresh access token without re-signing a JWT.

scope

string

The granted scope, echoed from the JWT's scope claim. Omitted for unrestricted (non-partner) sessions.

Launch a user via postMessage List assets

⌘I