Beta: we aim to avoid breaking changes, but they may occur before 1.0.
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 exampleRequires 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
- Go to Admin > API Management in the Dashboard.
- Sandbox: https://dashboard.sandbox.paxos.com/admin/api
- Production: https://dashboard.paxos.com/admin/api
- Create credentials and select the scopes your integration needs.
- Copy the Client ID and Client Secret and store them securely. The secret is not displayed again.
Manage credentials
- Read credentials from environment variables or a secret manager at startup. The examples in these docs use
PAXOS_CLIENT_IDandPAXOS_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.