Authentication

The API authenticates in three tiers. Log in to get a session token, mint customer API credentials with it, then issue a token per user. Each tier unlocks the next.

Send every request over HTTPS—plain HTTP fails. Treat every token and key like a password: keep them server-side, store them in a secrets manager or environment variables, and never ship them in browser or mobile code. Rotate on a schedule and revoke anything you suspect is exposed.

1. Account login (Bearer session token)

Log in with your Sovera account email and password. Login returns a Bearer session token. Send it as Authorization: Bearer <token> to manage your SX Customers resources—customers, the email poller, and webhooks.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

{
  "email": "[email protected]",
  "password": "your-password"
}

Send the returned token on every SX Customers request:

Authorization: Bearer YOUR_SESSION_TOKEN

2. Customer API credentials (owner x-api-key)

With your Bearer session token, mint API credentials for a customer. The endpoint returns a customer_secret—use it as your owner x-api-key for the SX Connect APIs: create and manage users, issue user tokens, and configure fees, currencies, and account data.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/CUSTOMER_ID/credentials" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

{
  "success": true,
  "data": {
    "customer_id": "sovbs-9f2a...",
    "customer_secret": "sk_live_8d3b..."
  },
  "meta": {
    "timestamp": "2026-06-07T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

Send the secret as your owner key on SX Connect requests:

x-api-key: YOUR_OWNER_API_KEY

3. User token (Bearer)

To act for one user, mint a user token with your owner x-api-key, then send it as Authorization: Bearer. A user token reaches only its own user's data on the SX Users APIs—wallets, addresses, transfers, withdrawals, trading, balances, and transactions. Tokens last about a year; cache one per user and reuse it until it expires rather than minting one per request.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/USER_ID/token" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

{
  "success": true,
  "data": {
    "token": "012d23b0d9a7d6c7d0b0429963eece727c4eca18635978d0bd6ffe6d1eaaed10",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "expires": "2027-06-07T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-06-07T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

Send the token as the user's Bearer credential on SX Users requests:

Authorization: Bearer YOUR_USER_TOKEN

Master API key (admin)

A few administrative endpoints—like listing every customer—take a master API key instead. Send it as x-master-api-key (these endpoints also accept it in x-api-key). It outranks an owner key, so guard it just as closely.

Security best practices

• Keep tokens and keys server-side—never in client-side code.
• Store credentials in environment variables or a secrets manager.
• Rotate keys on a schedule, and revoke anything that leaks.
• Call the API over HTTPS only.
• Monitor usage for anything unexpected.

Common errors

Authentication failures return the standard error envelope with a 401 or 403 status. See Error codes for the full shape.

401 Unauthorized

The request lacks valid credentials. Check the header, refresh an expired Bearer token, or regenerate a user token. Common causes:

• Missing or invalid x-api-key, or an inactive key.
• A missing or expired Authorization: Bearer token (account session or user token).

403 Forbidden

The credentials are valid but lack permission for this resource—for example, an owner key on a master-only endpoint. Use the credential that matches the tier.