Coinbax Core API

Session

The caller's own session lifecycle: who am I, refresh, log out. This is the slice of authentication an integrator needs. Account administration (register, password reset, OAuth account linking) stays private.

View as Markdown

Sign up for a staging account

POST/auth/signupPublic

Self-serve signup. Creates the account and sends a verification code. On staging the code is also returned in the response so the flow can be completed without an inbox; in production it is email-only.

Request body

  • emailstring (email)required
  • passwordstringrequired

    Requires upper, lower, number and special characters.

  • firstNamestringrequired
  • lastNamestringrequired
  • companyNamestring
  • intendedUseCasestring
  • waitlistReasonstring

Responses

201Account created; verification code issued

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

400Validation failed

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

409An account with that email already exists

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/auth/signup' \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "companyName": "string",
  "intendedUseCase": "string",
  "waitlistReason": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/auth/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "developer@example.com",
    "password": "string",
    "firstName": "string",
    "lastName": "string",
    "companyName": "string",
    "intendedUseCase": "string",
    "waitlistReason": "string"
  }),
});
const result = await response.json();

Redeem an email verification code

POST/auth/verify-codePublic

Runs the same verification the emailed link performs and provisions the identity so the account can sign in. Idempotent: a transient failure preserves the code so the call can be retried.

Request body

  • emailstring (email)required
  • codestringrequired

Responses

200Verified; the account can now sign in

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

400Code invalid or expired

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/auth/verify-code' \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "code": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/auth/verify-code', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "developer@example.com",
    "code": "string"
  }),
});
const result = await response.json();

Log in and obtain tokens

POST/identity/loginPublic

Authenticate with email and password. Accounts without MFA receive an access/refresh token pair; MFA-enabled accounts must complete the MFA challenge before receiving tokens. This is the current auth path — the identity service is the single source of truth for accounts since the Phase 5 cutover.

Request body

  • emailstring (email)required

    Normalised to lowercase server-side.

  • passwordstringrequired
  • environmentstring

    Optional identity environment selector.

Responses

200Credentials accepted. Returns an access/refresh token pair in `data`, or, for an MFA-enabled account, `data.requiresMfa: true` and `data.challengeToken` instead. Submit the challenge token and a TOTP or recovery code to `POST /identity/mfa/challenge` to obtain the token pair.

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

401Invalid credentials

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/identity/login' \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "password": "<your-password>"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/identity/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "you@example.com",
    "password": "<your-password>"
  }),
});
const result = await response.json();

Invalidate the current session

POST/identity/logoutPublic

Invalidates the refresh token immediately. The access token remains valid until it expires.

Request body

  • refreshTokenstringrequired

Responses

200Session invalidated

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/identity/logout' \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/identity/logout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "refreshToken": "string"
  }),
});
const result = await response.json();

Get the authenticated account

GET/identity/meBearer token

Returns the account behind the presented access token.

Responses

200Account returned
  • SuccessResponse
    • successenumrequiredtrue

      Always true for successful responses

    • dataobjectrequired

      Response data (structure varies by endpoint)

    • metaMetarequired
      • timestampstring (date-time)required

        Response timestamp

      • requestIdstringrequired

        Unique request identifier for debugging

      • paginationPagination
        • pageintegerrequired

          Current page number (1-indexed)

        • limitintegerrequired

          Items per page

        • totalintegerrequired

          Total number of items

        • totalPagesintegerrequired

          Total number of pages

  • object
    • dataIdentityAccount

      The signed-in account, as `GET /identity/me` returns it.

      • idstring (uuid)required
      • emailstring (email)required
      • firstNamestring
      • lastNamestring
      • avatarPathstringrequired

        Object path of the account's avatar in this deployment's environment, or null when it has none there. The identity directory is shared by staging and production but each keeps files in its own bucket, so the two hold separate avatars.

      • mfaEnabledbooleanrequired
      • statusenumrequired"active" · "inactive" · "suspended" · "pending_approval"
      • membershipsarray of objectrequired

        The account's active memberships, folded to one entry per environment: the union of their workspaces and scopes, with role `admin` if any of them is an admin membership.

        array of object
        • envenumrequired"staging" · "production"
        • workspaceIdsarray of string (uuid)required
          array of string (uuid)
          string (uuid)
        • roleenumrequired"admin" · "client"
        • scopesarray of stringrequired
          array of string
          string
      • platformAdminEnvsarray of enumrequired

        Environments where the account holds an active admin membership that is not tied to a workspace, sorted. Read this rather than `memberships` to tell a platform admin from a workspace admin: the fold gives a workspace admin of X and a platform admin who is also a member of X the same entry.

        array of enum
        enum"staging" · "production"
      • impersonatorIdstring (uuid)

        Present only while an admin is impersonating this account: the admin's account id.

{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "developer@example.com",
    "firstName": "string",
    "lastName": "string",
    "avatarPath": "identity-users/6f1d2c3b-0000-4000-8000-000000000001/0c2f6a1e-8b5d-4e7a-9f3c-2d1b4a6e8c90.png",
    "mfaEnabled": true,
    "status": "active",
    "memberships": [
      {
        "env": "staging",
        "workspaceIds": [
          "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
        ],
        "role": "admin",
        "scopes": [
          "string"
        ]
      }
    ],
    "platformAdminEnvs": [
      "staging"
    ],
    "impersonatorId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
  }
}
401Missing or invalid access token

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

curl 'https://core-staging.coinbax.com/api/v1/identity/me' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
const response = await fetch('https://core-staging.coinbax.com/api/v1/identity/me', {
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
  },
});
const result = await response.json();

Complete an MFA challenge and obtain tokens

POST/identity/mfa/challengePublic

Second leg of login when the account has MFA active. /identity/login returns a challengeToken instead of a token pair; exchange it here for the same access/refresh pair login would have returned. Accepts either a 6-digit TOTP or a recovery code. Input is trimmed and upper-cased before matching, so a pasted code with stray whitespace still works.

Request body

  • challengeTokenstringrequired

    The token returned by /identity/login.

  • codestringrequired

    A 6-digit TOTP, or a recovery code formatted XXXX-XXXX-XXXX. The recovery alphabet excludes the ambiguous I and O.

  • environmentstring

    Optional identity environment selector.

Responses

200Authenticated; same token pair as /identity/login

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

400Malformed code

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

401Challenge token expired or invalid, or code rejected

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/identity/mfa/challenge' \
  -H "Content-Type: application/json" \
  -d '{
  "challengeToken": "<token from /identity/login>",
  "code": "123456"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/identity/mfa/challenge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "challengeToken": "<token from /identity/login>",
    "code": "123456"
  }),
});
const result = await response.json();

Exchange a refresh token for a new access token

POST/identity/refreshPublic

Access tokens are short-lived. Exchange the refresh token rather than re-prompting for credentials.

Request body

  • refreshTokenstringrequired
  • environmentstring

Responses

200New tokens issued

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

401Refresh token invalid or expired

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

curl -X POST 'https://core-staging.coinbax.com/api/v1/identity/refresh' \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string",
  "environment": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/api/v1/identity/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "refreshToken": "string",
    "environment": "string"
  }),
});
const result = await response.json();