API Authentication
All requests to the server-to-server API (/api/v1) must be authenticated with a workspace API token.
Bearer token
Include the token in the Authorization header on every request:
Authorization: Bearer dotva_sk_...
Tokens are created per-workspace in "Developer Settings". Each token is bound to a single workspace — every resource is automatically scoped to that workspace.
| Condition | Response |
|---|---|
| Missing / invalid / expired / disabled token | 401 api.unauthenticated |
| Token belongs to a frozen / deleted workspace | 403 api.workspace_inactive |
| Calling IP not in the token's allowlist | 403 api.ip_not_allowed |
| Token lacks the required ability | 403 api.insufficient_ability |
IP allowlist
A token may optionally define an IP allowlist in CIDR notation. If set, any request originating from an IP outside the allowlist is rejected with 403 api.ip_not_allowed.
Leave the allowlist empty to allow all IPs (useful for development; tighten for production).
Workspace state
If the token's workspace is frozen or soft-deleted, all requests return 403 api.workspace_inactive regardless of the token's validity or abilities.
Token abilities
Each token is granted a set of abilities at creation time. Routes require specific abilities — a missing ability returns 403 api.insufficient_ability.
| Ability | Description | Applicable endpoints |
|---|---|---|
cards.read | Read cards and card transactions | GET /cards, GET /cards/{uuid}, GET /cards/{uuid}/transactions |
cards.write | Issue cards and run card lifecycle | POST /cards, topup / freeze / unfreeze / close |
orders.read | Read orders | GET /orders, GET /orders/{uuid} |
wallet.read | Read wallet balances | GET /wallet |
transactions.read | Read wallet ledger | GET /transactions |
Grant only the abilities your integration actually needs — follow the principle of least privilege.
Creating a token
- Navigate to Developer Settings in your workspace.
- Click New API Token.
- Enter a name, select abilities, and optionally set an IP allowlist and rate limit.
- Copy the token immediately — it is shown only once.
Tokens can be rotated or revoked from the same settings page at any time.