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
curl -s \
  -d '{"userId":"demo-123","walletAddress":"0xabc...","scopes":["cards.read","cards.write"]}' \
  https://dev-api.machines.cash/partner/v1/sessions

{
  "ok": true,
  "data": {
    "sessionToken": "<jwt>",
    "sessionId": "...",
    "userId": "...",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "scopes": ["cards.read","cards.write"]
  },
  "summary": "session created",
  "errors": []
}
2

Use the session token

Send Authorization: Bearer <token> on protected endpoints.
curl -s \
  -H 'Authorization: Bearer <SESSION_TOKEN>' \
  https://dev-api.machines.cash/partner/v1/cards
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
  • Withdrawals: withdrawals.write
Missing a scope returns 403 Forbidden.

​
All available scopes

Deposits and balances do not require extra scopes. 
users.read
users.write
kyc.read
kyc.write
cards.read
cards.write
cards.secrets.read
encryption.read
encryption.write
deposits.read
deposits.write
withdrawals.write

​
Headers quick reference

# Mint sessions (server-to-server)
X-Partner-Key: <YOUR_API_KEY>

# Call protected endpoints
Authorization: Bearer <SESSION_TOKEN>
Content-Type: application/json

# Optional Open Responses output
X-Open-Responses: 1
X-Open-Responses-Call-Id: <TOOL_CALL_ID>

​
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.