Skip to main content
Beta: we aim to avoid breaking changes, but they may occur before 1.0.
The Paxos API uses OAuth2 client credentials (machine to machine, with no user login). The SDKs acquire, cache and refresh access tokens for you. You provide a Client ID, a Client Secret and the scopes your integration needs when you construct the client.

Client credentials flow

The SDK selects the matching token URL and API base URL for the environment you configure.

Token lifecycle

  • The SDK requests a token on the first call and caches it.
  • A cached token is treated as expired 60 seconds before its expiry (or half its lifetime, if the token lives less than two minutes), so requests do not race a token that is about to expire.
  • Refresh is automatic. Only one refresh runs at a time, even with concurrent requests, so sharing one client across goroutines, threads or async tasks is safe.
  • If the API returns 401 for a request, the SDK refreshes the token and retries that request once.

Scopes

Scopes (Client Permissions) limit what a client can do. Pass at least one scope when you construct a client. The SDK returns or throws an error at construction if none are passed. Each language provides typed scope constants. Each method’s documentation states the scope it requires, for example Requires scope: transfer:read_transfer.
Scopes for each endpoint are listed in the API Reference docs. Market Data and most Pricing endpoints do not require authorization. The SDK client still requires at least one scope.

Get API credentials

  1. Go to Admin > API Management in the Dashboard.
  2. Create credentials and select the scopes your integration needs.
  3. Copy the Client ID and Client Secret and store them securely. The secret is not displayed again.
See Configure API Credentials for details.

Manage credentials

  • Read credentials from environment variables or a secret manager at startup. The examples in these docs use PAXOS_CLIENT_ID and PAXOS_CLIENT_SECRET.
  • Never hardcode credentials in source code or commit them to version control.
  • Grant each client only the scopes it needs.

Multiple environments

Sandbox and production are separate environments with separate credentials. Create one client per environment.

Authentication errors

If the token request fails, for example because of an incorrect Client Secret, the SDK raises a dedicated authentication error that carries the HTTP status. Confirm the credentials are for the environment you are targeting and that the requested scopes are enabled on the credentials.
Questions? Contact Support.