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

PermissionIn the key formWhat it reads
accounts.readAccounts and balancesYour accounts, numbers masked to the last 4 digits, and each currency's balance.
transactions.readTransactionsEvery line booked on your balances.
statements.readStatementsMonthly statements as JSON, CSV or PDF.
events.readAccount eventsWhat 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

  1. Open API keys

    Go to Settings › Developers (or Payments › VezmoPay › Developers). In Test keys or Live keys, select Generate key.

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

  3. 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.read and nothing else. The summary under the list says Read-only key and the start of the key ID it will get.

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

  5. 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 keyLive key
ReadsThe sandbox: simulated accounts, no real money. See Sandbox for the Accounts API.Your real accounts.
Key ID starts withvzm_test_ro_vzm_live_ro_
Secret starts withvzs_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_id and client_secret in the body.
  • To get a token that can do less than the key, send scope with 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

CodeWhat happenedWhat 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_expiredThe token is older than 15 minutes.Get a new token.
insufficient_scopeThe key, or the token you narrowed, lacks this endpoint's permission. scopes names it.Make a key with it.
api_access_not_enabledThe Accounts API isn't on for your business.Ask for access.
ip_not_allowedThe call came from an address the key doesn't allow.Add the address to the key's list.

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?