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

Source: https://vezmo.com/docs/developers/accounts-api-keys


## 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](/docs/developers/accounts-api-access).

## 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

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

**The secret is shown once:**
We keep only a fingerprint of it. If you lose it, roll the key: you get a new secret, and the old one keeps working
for the time you choose.

## Test keys and live keys

| | Test key | Live key |
| --- | --- | --- |
| Reads | The sandbox: simulated accounts, no real money. See [Sandbox for the Accounts API](/docs/developers/accounts-api-sandbox). | 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_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](https://user.vezmo.com/docs/v1/accounts-api#access-tokens).

## Change, roll or stop a key

Everything on [API keys](/docs/developers/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](/docs/developers/accounts-api-access). |
| `ip_not_allowed` | The call came from an address the key doesn't allow. | Add the address to the key's list. |

## Related

- [Accounts API](/docs/developers/accounts-api)
- [API keys](/docs/developers/api-keys)
- [Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api)

Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated
partners.
