Token Exchange Flow

Overview

This endpoint implements the OAuth 2.0 Token Exchange flow as defined in RFC 8693.

It allows trusted backend clients to obtain a short-lived, user-scoped access token to act on behalf of a specific user — based on access token issued by an external Identity Provider (e.g., Okta). This enables backend systems to securely send data or perform operations in the context of a user.

Prerequisites

Organizations that want to use the token exchange flow must contact our support team beforehand.

We will need to configure your Identity Provider (e.g., Okta) on our side to trust and validate tokens issued by your system.

Without this step, token exchange requests will be rejected.

Authentication

Access to this endpoint is restricted to authenticated clients only.

Before calling the Token Exchange Flow endpoint, the client must:

Authenticate using our API Key flow to obtain a client-scoped access token.
Use that token as a Bearer token in the Authorization header when making the token exchange request.

Token Exchange Request

Endpoint

Parameters

grant_type - should be set to urn:ietf:params:oauth:grant-type:token-exchange
subject_token - access token generated by external Identity Provider (e.g. Okta)
subject_token_type - should be set to urn:ietf:params:oauth:token-type:access_token
scope - should be se to fastauth:api:access

Required Claims in `subject_token`

An access token provided as subject_token (such as an Okta Access Token) must contain the following claims:

Claim	Required	Description
`scope`	Yes	Must include the value: `fastauth:api:access`
`organizationExternalId`	Yes	Must be a valid GUID identifying the organization
`email`	Yes	Must be a valid email

If the token is missing these claims or if the organizationExternalId is not in valid GUID format, the request will be rejected with 400 Bad Request.

Example payload of the access token that could be provided to this endpoint:

{
  "ver": 1,
  "jti": "AT.kzt5YGJVv1mCMxhVnz5ObCrueWmkzv4CGseUGPBy194",
  "iss": "https://your-custom-subdomain.okta.com/oauth2/default",
  "aud": "https://fastauth.com/",
  "iat": 1752763274,
  "exp": 1752766874,
  "cid": "0oaswv4m025ElkoL6697",
  "uid": "00uswt3qgkJheySgD697",
  "scp": [
    "fastauth:api:access"
  ],
  "auth_time": 1000,
  "sub": "user@yourcustomdomain.com",
  "organizationExternalId": "00000000-0000-0000-0000-000000000000",
  "email": "user@yourcustomdomain.com"
}

Response

As a response, a FastAuth access token is provided, which can be used to access all endpoints exposed by our external API. It is the same token that is generated using the API Key Authentication flow, but here it is scoped to a specific user. The other flow generates a token for a technical user configured for the organization.

Token Exchange Flow

Overview​

Prerequisites​

Authentication​

Token Exchange Request​

Endpoint​

Parameters​

Required Claims in subject_token​

Response​