Skip to main content

​
Two credentials

  • API key: send with X-Partner-Key for server‑to‑server calls (mint sessions). Never expose it to clients.
  • Session token: short‑lived JWT for protected endpoints. Send with Authorization: Bearer <token>.

​
Flow

​
API flows (step‑by‑step)

1

Create a session token (server-to-server)

Endpoint: POST /sessions
Body:
  • userId (string, your user id)
  • walletAddress (0x… address, optional)
  • scopes (array of strings)
  • ttlSeconds (integer, optional)
Response:
  • sessionToken (use as Authorization: Bearer <token>)
  • sessionId, userId, expiresAt, scopes
2

Use the session token

Send Authorization: Bearer <token> on protected endpoints.
Missing/expired tokens return 401; missing permissions return 403.
3

Renew when expired

Tokens are short‑lived. Mint a new session when you get 401 Unauthorized.
4

Scope presets by task

Keep scopes minimal. Common sets:
  • KYC: kyc.read, kyc.write
  • Cards: cards.read, cards.write
  • Card secrets: cards.secrets.read
  • Card labels: encryption.write (encrypt), encryption.read (decrypt)
  • Balances: no extra scopes
  • Transactions: transactions.read
  • Withdrawals: withdrawals.write
Missing a scope returns 403 Forbidden.

​
All available scopes

Deposits and balances do not require extra scopes.

​
Headers quick reference

​
Token basics

  • Short‑lived by default (e.g., ~15 minutes). Rotate by minting a new session.
  • Session payload includes account id, user id, wallet address, scopes, expiry.
  • Never log tokens or card data; always use HTTPS.
Use https://dev-api.machines.cash in sandbox. Switch to production only after key validation.