Coinbax has two API surfaces with different authentication:
| API | Base URL (staging) | Auth |
|---|---|---|
| Payments API | https://api-staging.coinbax.com/api/v2 |
OAuth 2.0 Bearer token |
| Workspace API | https://core-staging.coinbax.com/api/v1 |
Authorization: Bearer <JWT>, or an OAuth 2.0 Bearer token on server-to-server routes |
Production bases are https://api.coinbax.com/api/v2 and
https://core.coinbax.com/api/v1. Staging credentials only work against
staging; the environments share nothing.
API keys are deprecated
API keys (X-API-Key) are deprecated on both APIs. Use OAuth 2.0 client
credentials, described below. The Payments API v2 does not accept keys, and
every Workspace API route that still takes one also takes an OAuth token.
Removal dates will be announced in API versioning
before keys stop working.
Short lived tokens are the reason for the change: a leaked key is valid until somebody notices and regenerates it, whereas a leaked token expires on its own.
OAuth 2.0 client credentials (service-to-service)
For service-to-service integrations, use the OAuth 2.0 client_credentials
grant. You exchange a client ID and secret for a Bearer token, then send that
token on each request.
The two APIs issue their own clients and tokens. A token from one does not work on the other, so an integration that calls both holds two clients:
| Payments API client | Workspace API client | |
|---|---|---|
| Create it | Workspace API, POST /workspaces/{id}/oauth/clients |
Workspace API, POST /workspaces/{id}/workspace-oauth/clients, or the Coinbax portal |
| Token endpoint | https://api-staging.coinbax.com/api/v2/oauth/token |
https://core-staging.coinbax.com/api/v1/oauth/token |
| Token response | Standard response envelope (data.access_token) |
RFC 6749 JSON (access_token) |
| Scopes | Payments API scopes | Workspace API scopes |
Create a Payments API client
Payments API clients are managed on the Workspace API and authenticated
with your workspace JWT. There is no client-creation endpoint on /api/v2: a
credential that can mint credentials belongs with the rest of workspace
administration.
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/$WORKSPACE_ID/oauth/clients \
-H "Authorization: Bearer $WORKSPACE_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "My Backend Service",
"scopes": ["read:transactions", "write:transactions"],
"grantTypes": ["client_credentials"]
}'
The response includes clientId and clientSecret. The secret is shown
once.
Create a Workspace API client
Like Payments API clients, Workspace API clients are created on the Workspace
API with your workspace JWT, but at their own endpoint:
POST /workspaces/{id}/workspace-oauth/clients.
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/$WORKSPACE_ID/workspace-oauth/clients \
-H "Authorization: Bearer $WORKSPACE_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "My Workspace Integration",
"scopes": ["read:transactions", "write:wallets"]
}'
If you leave out scopes, the client gets read:transactions and
read:customers. The response includes clientId and clientSecret. The
secret is shown once.
You can also create one in the Coinbax portal: open your workspace, go to Workspace API clients and pick the scopes the integration needs.
Exchange credentials for a token
Payments API:
curl -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "coinbax_client_...",
"client_secret": "coinbax_secret_...",
"scope": "read:transactions write:transactions"
}'
scope is optional and space-separated; omit it to receive all scopes
granted to the client. The token arrives in the standard response envelope:
{
"success": true,
"data": {
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read:transactions write:transactions"
},
"meta": { "timestamp": "...", "requestId": "..." },
"error": null
}
Use data.access_token from the Payments response as PAYMENTS_TOKEN:
curl https://api-staging.coinbax.com/api/v2/transactions \
-H "Authorization: Bearer $PAYMENTS_TOKEN"
Workspace API: the token endpoint takes a form-encoded body, with the client
credentials in HTTP Basic auth (or as client_id and client_secret form
fields).
curl -X POST https://core-staging.coinbax.com/api/v1/oauth/token \
-u "$WORKSPACE_CLIENT_ID:$WORKSPACE_CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope=read:transactions
It answers in the RFC 6749 shape, without the envelope:
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read:transactions"
}
Use access_token from the Workspace response as WORKSPACE_TOKEN to fetch
a workspace transaction (requires read:transactions):
curl "https://core-staging.coinbax.com/api/v1/workspaces/$WORKSPACE_ID/transactions/$TRANSACTION_ID" \
-H "Authorization: Bearer $WORKSPACE_TOKEN"
Token lifecycle: cache, refresh, retry
Do not request a new token per API call. The correct pattern:
- Cache the
access_tokenwith its computed expiry (now + expires_inseconds). - Refresh early. Treat the token as expired about 60 seconds before its actual expiry so in-flight requests never race the deadline.
- Share in-flight refreshes. If multiple concurrent requests find the cache empty, they should await one token request, not fan out N of them.
- Retry on 401. If a request returns 401 with a token you believed valid (revocation, clock skew), discard the cached token, fetch a fresh one, and retry the request once.
createTokenProvider returns a cached token getter for one OAuth client.
Create one per client, each with that client’s own credentials. The Payments
API token endpoint takes JSON and the Workspace API token endpoint takes a
form-encoded body. The getter’s invalidate(token) drops a token the API
rejected, and fetchWithToken uses it for the single retry in step 4.
function createTokenProvider({ tokenUrl, json, clientId, clientSecret }) {
let cached = null; // { token, expiresAt }
let inflight = null;
async function fetchToken() {
const credentials = {
grant_type: "client_credentials",
client_id: clientId,
client_secret: clientSecret,
};
const res = await fetch(tokenUrl, {
method: "POST",
headers: {
"Content-Type": json ? "application/json" : "application/x-www-form-urlencoded",
},
body: json ? JSON.stringify(credentials) : new URLSearchParams(credentials),
});
if (!res.ok) throw new Error(`Token request to ${tokenUrl} failed with ${res.status}`);
const body = await res.json();
// The Payments API wraps the token in its response envelope; the Workspace API does not.
const token = body.data ?? body;
return { token: token.access_token, expiresAt: Date.now() + token.expires_in * 1000 };
}
async function getAccessToken() {
if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
inflight ??= fetchToken().finally(() => { inflight = null; });
cached = await inflight;
return cached.token;
}
// Drop a token the API rejected, unless a newer one has already replaced it.
getAccessToken.invalidate = (token) => {
if (cached?.token === token) cached = null;
};
return getAccessToken;
}
const getPaymentsToken = createTokenProvider({
tokenUrl: "https://api-staging.coinbax.com/api/v2/oauth/token",
json: true,
clientId: process.env.COINBAX_CLIENT_ID,
clientSecret: process.env.COINBAX_CLIENT_SECRET,
});
const getWorkspaceToken = createTokenProvider({
tokenUrl: "https://core-staging.coinbax.com/api/v1/oauth/token",
json: false,
clientId: process.env.WORKSPACE_CLIENT_ID,
clientSecret: process.env.WORKSPACE_CLIENT_SECRET,
});
// Sends the request with a token, and on a 401 retries once with a fresh one.
async function fetchWithToken(getToken, url, init = {}) {
const send = (token) => {
const headers = new Headers(init.headers);
headers.set("Authorization", `Bearer ${token}`);
return fetch(url, { ...init, headers });
};
const token = await getToken();
const res = await send(token);
if (res.status !== 401) return res;
getToken.invalidate(token);
return send(await getToken());
}
const res = await fetchWithToken(getPaymentsToken, "https://api-staging.coinbax.com/api/v2/transactions");
The code samples in the API reference call getPaymentsToken() on Payments
API pages and getWorkspaceToken() on Workspace API pages.
Revoke a single Payments API token with POST /oauth/revoke on the Payments
API.
Revoking every token for a client, and client management generally, lives on
the Workspace API:
POST /workspaces/{id}/oauth/clients/{clientId}/revoke-tokens. One resource,
one home — the Payments API used to publish a duplicate of this surface under
a slightly different name, and from v2 it does not.
JWT (Workspace API)
The Workspace API authenticates humans and dashboard-style integrations with JWTs:
# Log in to obtain tokens
curl -X POST https://core-staging.coinbax.com/api/v1/identity/login \
-H "Content-Type: application/json" \
-d '{ "email": "you@example.com", "password": "..." }'
# Use the access token
curl https://core-staging.coinbax.com/api/v1/workspaces/me \
-H "Authorization: Bearer <access-token>"
Log in against /identity/login. The identity service is the single source of
truth for accounts, and /auth/login is not a live route despite appearing in
older material — a call to it returns a bare Bad request. rather than a
Coinbax error envelope.
Access tokens expire after one hour. Use POST /identity/refresh to obtain a
new access token without re-authenticating, and POST /identity/logout to
invalidate the session. Both take the refresh token in the body.
Choosing a method
| You are building | Use |
|---|---|
| A backend that creates payments | OAuth 2.0 client credentials, Payments API client |
| A backend that manages workspace customers or wallet sign-in | OAuth 2.0 client credentials, Workspace API client |
| A tool against workspace data (customers, settings, webhooks) | Workspace API with JWT |
| Anything in a browser or mobile app | OAuth via your own backend proxy; never embed client secrets or tokens client-side |
Next steps
- API scopes: what each scope grants and how the hierarchy works
- Errors and the response envelope: what 401 and 403 responses look like
- Payments API reference: the auth and OAuth endpoints in full