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/signupBearer token

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/auth/signup \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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/auth/signup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    '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-codeBearer token

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/auth/verify-code \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "code": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/auth/verify-code', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    '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/loginBearer token

Authenticate with email and password and receive an access/refresh token pair. 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

200Authenticated; tokens returned

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/identity/login \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "password": "<your-password>"
}'
const response = await fetch('https://core-staging.coinbax.com/identity/login', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    '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/logoutBearer token

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/identity/logout \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/identity/logout', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    '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

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

401Missing or invalid access token

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

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

Exchange a refresh token for a new access token

POST/identity/refreshBearer token

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/identity/refresh \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string",
  "environment": "string"
}'
const response = await fetch('https://core-staging.coinbax.com/identity/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "refreshToken": "string",
    "environment": "string"
  }),
});
const result = await response.json();