Coinbax API

OAuth 2.0

View as Markdown

Revoke access token

POST/api/v2/oauth/revokeOAuth 2.0 client credentials

Revoke an active access token by its JWT ID (jti)

Request body

  • token_jtistringrequired

    JWT ID (jti) of the token to revoke

Responses

200Token revoked successfully

Response follows the unified success / data / meta / error envelope.

404Token not found
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
# Exchange the client ID and secret for an access token (requires jq)
ACCESS_TOKEN=$(jq -n '{grant_type: "client_credentials", client_id: env.COINBAX_CLIENT_ID, client_secret: env.COINBAX_CLIENT_SECRET, scope: "write:platform"}' |
  curl -sS -X POST https://api-staging.coinbax.com/api/v2/oauth/token \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r .data.access_token)

# Call the endpoint with the token
curl -X POST 'https://api-staging.coinbax.com/api/v2/oauth/revoke' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "token_jti": "550e8400-e29b-41d4-a716-446655440000"
}'
// getPaymentsToken() is the cached client_credentials helper in /docs/api/authentication
const response = await fetch('https://api-staging.coinbax.com/api/v2/oauth/revoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${await getPaymentsToken()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "token_jti": "550e8400-e29b-41d4-a716-446655440000"
  }),
});
const result = await response.json();

List available OAuth scopes

GET/api/v2/oauth/scopesPublic

Get the catalog of available OAuth scopes that can be assigned to clients

Responses

200List of available scopes
array of OAuthScope
object
[
  {}
]
curl 'https://api-staging.coinbax.com/api/v2/oauth/scopes'
const response = await fetch('https://api-staging.coinbax.com/api/v2/oauth/scopes', {
});
const result = await response.json();

OAuth 2.0 Token Endpoint

POST/api/v2/oauth/tokenPublic

Generate access token using Client Credentials flow (RFC 6749)

Request body

  • grant_typeenumrequired"client_credentials"

    OAuth 2.0 grant type

  • client_idstringrequired

    OAuth client ID

  • client_secretstringrequired

    OAuth client secret

  • scopestring

    Space-separated list of requested scopes (optional, defaults to all client scopes)

Responses

200Access token generated successfully
  • access_tokenstringrequired

    JWT access token

  • token_typestringrequired

    Token type (always Bearer)

  • expires_innumberrequired

    Token expiration time in seconds

  • scopestringrequired

    Space-separated list of granted scopes

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:transactions write:transactions"
}
400Invalid request or unsupported grant type
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
401Invalid client credentials
  • successbooleanrequired

    Always `false` on an error response.

  • dataenumrequired

    Always `null` on an error response. Present so success and error bodies share a shape.

    enumnull

    Always `null` on an error response. Present so success and error bodies share a shape.

  • metaErrorResponseMetaDtorequired
    • timestampstringrequired

      ISO 8601 timestamp of the response.

    • requestIdstringrequired

      Request id for this response. Echoes the `X-Request-ID` or `X-Correlation-ID` you sent, whatever its format; when you send neither, the server generates a UUID v4. Quote it when reporting a problem — it is how the request is found in our logs.

    • pathstringrequired

      Request path that produced the error.

    • methodstringrequired

      HTTP method of the request that produced the error.

  • errorApiErrorDtorequired
    • codestringrequired

      Machine-readable error code. Branch on this rather than on `message`, which is free text and may change. Deliberately an open string, NOT a closed enum. Two families of code reach this field: - the status-derived codes in `ErrorCode` (VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, and so on), which `AllExceptionsFilter` assigns from the HTTP status; - domain-specific codes a service sets on the exception it throws, such as `ESCROW_ALREADY_CREATED`, `PRE_ESCROW_PENDING` or `RELEASE_WINDOW_NOT_ELAPSED`. The second family is the larger one, so publishing `ErrorCode` as an enum would make a strict client reject most real error responses. Treat an unrecognised code as its HTTP status.

    • messagestringrequired

      Human-readable description of what went wrong.

    • statusCodenumberrequired

      HTTP status code, repeated here so the body is self-contained.

    • detailsone of

      Structured context for the error, such as per-field validation messages. Shape varies by `code`; treat it as opaque unless you recognise the code.

      • object
        object
      • array of object
        array of object
        object
      • string
        string
    • suggestionstring

      Actionable guidance for fixing the request, intended to be shown to a person. Advice, not data.

{
  "success": false,
  "data": null,
  "meta": {
    "timestamp": "2026-11-06T12:34:56.789Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/transactions",
    "method": "POST"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 400,
    "details": {
      "amount": "must be a positive number"
    },
    "suggestion": "Use one of: base, ethereum"
  }
}
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_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
  "scope": "read:transactions write:transactions"
}'
const response = await fetch('https://api-staging.coinbax.com/api/v2/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "grant_type": "client_credentials",
    "client_id": "coinbax_client_a1b2c3d4e5f6g7h8i9j0",
    "client_secret": "coinbax_secret_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q0",
    "scope": "read:transactions write:transactions"
  }),
});
const result = await response.json();