Authentication Guide

CROSSFX API · AUTHENTICATION

Authenticate once. Use the token across the API.

Exchange your CrossFX client credentials for a short-lived bearer token using the OAuth 2.0 client-credentials grant.

Send the resulting access token on every subsequent API request. No user interaction, redirect or per-endpoint authentication is required.

OAuth 2.0Client credentialsBearer tokenShort-lived

How authentication works

CrossFX uses a standard machine-to-machine OAuth 2.0 flow.

01

Client credentials

client_id + client_secret

→

02

Access token

grant_type=client_credentials

→

03

Authenticated calls

Authorization: Bearer <access_token>

Machine to machine

No user interaction

The client-credentials grant requires no login screen, user consent or redirect.

Short-lived tokens

Refresh before expiry

The token response carries `expires_in`, allowing your client to obtain a replacement before the current token expires.

One token

Use it across CrossFX

The same bearer token authenticates every API endpoint your client is authorised to call.

Before you start

You need CrossFX-issued client credentials before requesting a token.

Production credentials

Issued during onboarding

Email [onboarding@crossfx.com](mailto:onboarding@crossfx.com) if your team does not yet have client credentials.

Sandbox credentials

Use the shared test credentials

The [Sandbox Data & Testing Guide](/sandbox-data-testing-guide-2215948m0) contains credentials for the Sandbox environment.

They authenticate Sandbox only.

Get an access token

Get Access Token

Token endpoint

`POST /realms/{realm}/protocol/openid-connect/token`

Open the API Reference for the complete request and response schemas and an interactive console.

REQUEST FORMAT

The token request is not JSON.

Send grant_type, client_id and client_secret as form-encoded parameters. The response returns access_token, token_type and expires_in.

Token path

The token endpoint is realm-specific:

/realms/{realm}/protocol/openid-connect/token

For Sandbox, use the sandbox realm.

Using the token

Send the access token on every API request other than the token request itself.

AUTHORIZATION HEADER

Authorization: Bearer <access_token>

A malformed Authorization header is rejected before request validation runs.

Token lifecycle

VALID TOKEN

Continue using it

One token can be used across the API until it approaches expiry.

APPROACHING EXPIRY

Refresh proactively

Use expires_in to obtain a replacement token before the current token expires.

401 RESPONSE

Re-authenticate

A missing, malformed or expired token returns 401. Obtain a new token and retry.

Authentication rules

Grant type

Only client_credentials is supported

`grant_type` must be exactly `client_credentials`. No other OAuth grant is supported.

Request encoding

Use form encoding

Send `grant_type`, `client_id` and `client_secret` as form-encoded parameters, not JSON.

Realm

The realm is part of the token path

Use `/realms/{realm}/protocol/openid-connect/token`.

The Sandbox realm is `sandbox`.

Expiry

Refresh before expires_in

An expired token is rejected with `401` by every API endpoint.

ERROR ENVELOPE

The token endpoint is an OAuth 2.0 endpoint, so its failures use { "error": …, "error_description": … }. This is different from CrossFX platform errors returned by other endpoints, which use { "error", "code", …, "error_id" }.

Errors

The token endpoint returns the OAuth 2.0 error envelope:

{ "error": …, "error_description": … }

The code column below is the value of the OAuth 2.0 error field.

HTTP	`code`	Trigger	What you do
400	`invalid_request`	A required form parameter is missing: `grant_type`, `client_id`, or `client_secret`	Send the missing parameter
400	`unsupported_grant_type`	`grant_type` is present but is not `client_credentials`	Use `client_credentials`
401	`invalid_client`	The client id is not recognised	Check the client id, then contact support
401	`unauthorized_client`	The client secret does not match	Check the secret, then contact support
500	`server_error`	An unexpected internal error	Retry with backoff

401 from the rest of the API

A missing, malformed or expired bearer token on another endpoint returns:

{ "message": "Unauthorized" }

This is different from an error returned directly by the OAuth token endpoint.

How authentication works#

Before you start#

Get an access token#

Token path#

Using the token#

Token lifecycle#

Authentication rules#

Errors#

401 from the rest of the API#

Test token expiry in Sandbox#