Keys and permissions for the Accounts API
The four Accounts API permissions and what each reads, choosing them when you generate a key, test and live keys, live keys before VezmoPay, the key ID and secret, getting an access token from POST /oauth/token, and what each refusal means.
Overview
An Accounts API call is made with an API key that holds Accounts API permissions. You choose them when you generate the key; a key starts with no permissions at all. Every Accounts API permission only reads, so a key that holds only these is a read-only key.
The permissions open once the Accounts API is on for your business. See Get access to the Accounts API.
The four permissions
| Permission | In the key form | What it reads |
|---|---|---|
accounts.read | Accounts and balances | Your accounts, numbers masked to the last 4 digits, and each currency's balance. |
transactions.read | Transactions | Every line booked on your balances. |
statements.read | Statements | Monthly statements as JSON, CSV or PDF. |
events.read | Account events | What happened on your accounts in the last 30 days. |
The names have a dot and end in .read, like the rest of Vezmo's permissions. Don't mix up accounts.read (the
Accounts API) with account.read, which reads your payment settings (3D Secure and payment methods) and sits under
Account security in the key form.
Generate a key with Accounts API permissions
Open API keys
Go to Settings › Developers (or Payments › VezmoPay › Developers). In Test keys or Live keys, select Generate key.
Name the key
Name it after where it runs, like "ERP sync". The description is optional. A live key with Accounts API permissions must expire: leave the date empty and it expires after 180 days, or pick a date up to 365 days ahead.
Choose the permissions
Under Accounts API · read only, set each one you need to Read. Choose only what the system needs: a statement exporter needs
statements.readand nothing else. The summary under the list says Read-only key and the start of the key ID it will get.Confirm it's you
Select Generate key. We email you a code and ask for your passkey or authenticator app, because a key reads your money.
Save the key ID and the secret
Both are shown once. Keep the secret in a secrets manager on your server, never in code, a web page or version control. Then select I've saved them — done.
Test keys and live keys
| Test key | Live key | |
|---|---|---|
| Reads | The sandbox: simulated accounts, no real money. See Sandbox for the Accounts API. | Your real accounts. |
| Key ID starts with | vzm_test_ro_ | vzm_live_ro_ |
| Secret starts with | vzs_test_ | vzs_live_ |
A key's mode never changes. A test key never sees live data, and a live key never sees the sandbox.
Before VezmoPay is active, a live key can still be made once the Accounts API is on, holding only Accounts API
permissions. The key form then lists them first and shows the others as Opens with VezmoPay. A live key that asks
for any other permission is refused with 403 and the code LIVE_KEYS_NEED_VEZMOPAY.
Get an access token
Your server swaps the key for an access token with POST /oauth/token, the standard OAuth 2.0 client-credentials
request, so any OAuth library works:
- Send
grant_type=client_credentials, form-encoded or as JSON. - Send the key ID and the secret one way: HTTP Basic, or as
client_idandclient_secretin the body. - To get a token that can do less than the key, send
scopewith the permissions you want, separated by spaces.
The answer has access_token, token_type (Bearer), expires_in (900 seconds, so 15 minutes) and scope. There
is no refresh token: when the token runs out, ask for a new one. A key can get 10 tokens a minute, so keep the token
and reuse it until it ends.
Requests and answers with examples: Authentication in the Accounts API reference.
Change, roll or stop a key
Everything on API keys applies to these keys too. In short:
- Remove permissions at any time. You can't add any: make a new key instead.
- Roll a key to get a new secret; the old one keeps working for 1 hour, 24 hours or 7 days.
- Allowed IP addresses: a key that should run only from your servers can be limited to their addresses.
- Revoke a key in one click: it stops at once.
- Found in public code. If GitHub finds one of your secrets in public code, we tell every admin of your business. A live key is revoked at once. A test key can no longer make sandbox simulations, and the notice offers Revoke it now.
When a call is refused
| Code | What happened | What to do |
|---|---|---|
invalid_client (from /oauth/token) | The key ID or secret is wrong, or the key is switched off, revoked or expired. | Check the key; roll it if the secret is lost. |
invalid_scope (from /oauth/token) | You asked for a permission the key doesn't hold. | Leave it out, or make a key with it. |
token_expired | The token is older than 15 minutes. | Get a new token. |
insufficient_scope | The key, or the token you narrowed, lacks this endpoint's permission. scopes names it. | Make a key with it. |
api_access_not_enabled | The Accounts API isn't on for your business. | Ask for access. |
ip_not_allowed | The call came from an address the key doesn't allow. | Add the address to the key's list. |
Related
Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated partners.
Facts checked against the product on 14 Nov 2026.
Was this page helpful?
Get access to the Accounts API
How to ask for the Accounts API, how we switch it on for your business, what the Accounts API card shows, what changes once it is on, and what happens if it is switched off.
Statements by API
Read your monthly account statements with the Accounts API, covering one statement per account per month, when a month is final, JSON, CSV and PDF, large months in parts, what the CSV columns hold, masked account details, limits and the statement.available event.