Guides

Authentication

OAuth 2.0 client credentials and JWT authentication for the Coinbax Payments and Workspace APIs.

Last updated 2026-11-19View as Markdown

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:

  1. Cache the access_token with its computed expiry (now + expires_in seconds).
  2. Refresh early. Treat the token as expired about 60 seconds before its actual expiry so in-flight requests never race the deadline.
  3. Share in-flight refreshes. If multiple concurrent requests find the cache empty, they should await one token request, not fan out N of them.
  4. 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