> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Hold several API keys, give each one a role, and rotate them without downtime.

Each API key comes with its own Client ID. Together they get a token, as [Authentication](https://docs.kirafin.ai/get-started/authentication.md) shows. You can hold several keys, give each one only the access it needs, and revoke one without touching the others.

You manage keys in the dashboard, under **Developers → API Keys**. An API key cannot create, edit or revoke keys, so a leaked key cannot make another.

> [!NOTE]
>
> Key creation is being turned on account by account. If **Developers → API Keys** shows only your credentials and no **Create API key** button, ask your Kira contact to turn it on.

## Your default key

The key Kira provisioned for you is your **default key**. It keeps working exactly as it always has.

* It has **Full access**, and its role cannot be changed.
* It cannot be revoked.
* Its Client ID is the UUID you already use.

Keys you create need no legacy key. Only the default key ever had one.

## Create a key

Each environment manages its own keys. A key created in the sandbox dashboard works only in sandbox, and a production key works only in production.

**1. Open the list**

In the dashboard for the environment you need, go to **Developers → API Keys** and select **Create API key**.

**2. Describe the key**

Give it a name, so you can tell it apart from the others, and an optional description. Choose a [role](#roles).

**3. Copy the Client ID and the API key**

Both appear once, in **Your new API key**. This is the only time the dashboard shows the API key, so store it before you select **I've saved it**. If you lose it, create a new key and revoke the old one.

Only people with the Administrator [role](https://docs.kirafin.ai/dashboard/roles.md) can create, edit and revoke keys. Everyone else on your team can see the list: each key's name, Client ID, role and status, who created it and when, and when it was last used. **Last used** is updated at most once an hour.

All your keys share your account's [rate limit](https://docs.kirafin.ai/using-the-api/rate-limits.md). Creating more keys does not raise it.

## Roles

A key's role decides what the key can do. Every role reads everything the key reaches and can price a movement. The difference is what each role can change.

| What the key can do | Full access | Operations | Compliance | Viewer |
| - | :-: | :-: | :-: | :-: |
| Read users, accounts, balances, deposits, payouts, recipients and requests for information | ✓ | ✓ | ✓ | ✓ |
| Price a movement: create a quotation, preview a payout | ✓ | ✓ | ✓ | ✓ |
| Create and update users | ✓ | ✓ | ✓ | — |
| Create recipients | ✓ | ✓ | ✓ | — |
| Answer a request for information, upload or remove a document, send a beneficiary's verification link | ✓ | ✓ | ✓ | — |
| Open and update virtual accounts, and simulate a deposit in sandbox | ✓ | ✓ | — | — |
| Execute a payout | ✓ | ✓ | — | — |

[Pin account to a version](https://docs.kirafin.ai/api-reference/versioning/pin-account-to-a-version.md) moves the whole account, so only the default key can call it.

A key's role is separate from the role of the person who created it. Full access is the key's equivalent of the dashboard's Administrator. The dashboard's Developer role is not offered for keys, because through the API it can do no more than Viewer.

To change a key's role, select **Edit** on the key. The new role applies within seconds, with no new token.

## When a role does not allow the call

The call is refused with a `403`, and nothing is created or changed.

```json theme={null}
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key does not allow this action",
  "timestamp": "2026-10-06T15:04:05.000Z",
  "path": "/v1/virtual-accounts/3f9c1a52-8d4e-4b7a-9e21-6a0c5d7f8b13/payout"
}
```

The body carries no `code`. Make the call with a key whose role allows it, or ask an administrator to change this key's role.

## Limit a key to some sub-clients

A key can reach every sub-client, or only the sub-clients you list. A sub-client is a [user](https://docs.kirafin.ai/api-reference/users/get-a-user.md) in the API, and you list it by its `id`.

When you create or edit a key, choose **All sub-clients** or **Only these sub-clients**, then pick the sub-clients. A key that reaches only some sub-clients still has its [role](#roles). The role decides what the key can do, and the list decides where it can do it.

* Your default key always reaches every sub-client, and cannot be limited.
* A key limited to an empty list reaches no sub-client.
* A sub-client created with a limited key joins that key's list.
* Listings return only the sub-clients on the list, and the accounts, deposits, payouts, recipients and requests for information that belong to them.
* A new scope applies within seconds. Adding or removing a sub-client applies from the next request.

A limited key can call every endpoint in this reference except [Pin account to a version](https://docs.kirafin.ai/api-reference/versioning/pin-account-to-a-version.md). Three calls check more with it:

* [Create a quotation](https://docs.kirafin.ai/api-reference/quotations/create-a-quotation.md) for a virtual account needs that account to belong to a listed sub-client.
* [Preview a payout](https://docs.kirafin.ai/api-reference/payouts/preview-a-payout.md) and [Execute a payout](https://docs.kirafin.ai/api-reference/payouts/execute-a-payout.md) need the recipient to belong to the same sub-client as the virtual account.

### When a key reaches outside its sub-clients

The call is refused with a `403`, and nothing is created or changed. Read `code`:

| `code` | It means |
| - | - |
| `api_key_subclient_out_of_scope` | The sub-client is not on the key's list. An ID that does not exist gets the same answer. |
| `api_key_recipient_subclient_mismatch` | The recipient belongs to a different sub-client than the virtual account. |
| `api_key_route_not_allowed` | A limited key cannot call this endpoint. Use a key that reaches every sub-client. |

```json theme={null}
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This API key does not reach this sub-client",
  "timestamp": "2026-10-06T15:04:05.000Z",
  "path": "/v1/users/6d0f8a3e-2b1c-4e7f-9a5d-3c8b1e2f4a60",
  "code": "api_key_subclient_out_of_scope"
}
```

## Rotate a key

There is no downtime, because two keys work at the same time until you revoke one.

**1. Create the new key**

Give it the same role as the key it replaces.

**2. Deploy it**

Put the new Client ID and API key in your integration, and check that it gets tokens with them.

**3. Revoke the old key**

Calls with the old key stop. Calls with the new one carry on.

There is no way to regenerate a key in place. Your default key cannot be revoked, so to stop using it, move your integration to a key you created.

## Revoke a key

Select **Revoke** on the key and confirm. If the key has been used, the confirmation shows when it was last used.

Calls with the key stop within seconds, and your other keys keep working. The key can no longer get a token. A call made with a token it already holds is refused with a `401` and `code` `api_key_revoked`, or with a `403` once the request is turned away before it reaches the API.

Revoking cannot be undone. A revoked key stays in the list, marked **Revoked**, and can no longer be edited.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.