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

# API Key Scopes

Each API key has a scope. The scope sets what the key can do. Give each key the smallest scope that its integration needs. For example, a reporting job needs only Read only.

## Scopes

| Scope | API value | What the key can do |
| - | - | - |
| Full access | `full_access` | Everything that an admin of your team can do |
| Operate | `operate` | Move money to recipients that already exist, and run your daily operations |
| Read only | `read_only` | Read data only |

The scopes nest. Operate can do everything that Read only can do, and Full access can do everything that Operate can do.

When a key calls an endpoint that its scope does not allow, the API returns `403 Forbidden`.

### What Operate can do

An Operate key can:

* Create and update customers.
* Create and update onramps, offramps and swaps.
* Create one-off transactions, and cancel transactions.
* Create and cancel scheduled payments.
* Create wallets with the signer groups and policies that you already have.
* Create, update and freeze cards.
* Update recipients: their names, postal addresses and accepted assets.
* Clear exceptions.
* Run sandbox simulations.

### What Operate cannot do

An Operate key cannot:

* Add recipients or destinations. An Operate key sends money only to destinations that already exist.
* Delete anything.
* Manage agentic payments: create instructions, create or revoke payment agents, create, approve or cancel mandates, or change your agentic policy. An instruction can add recipients and destinations when it runs, and a payment agent adds a signer.
* Invite, change or remove team members, or create, change or revoke API keys.
* Add or change signers, signer groups, policies or webhook targets, change the signer groups of a wallet, or change where your payouts go.
* Show full card details or buy credits.

If your integration must add recipients, use a Full access key for that step.

## Create a key with a scope

In the dashboard, you choose the scope when you create the key. There is no default.

Through the API, send `scope` in the body of `POST /api-keys`:

```bash cURL theme={null}
curl -X POST https://api.platform.dakota.xyz/api-keys \
  -H "x-api-key: $DAKOTA_API_KEY" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "reporting", "scope": "read_only"}'
```

If you leave out `scope`, the API gives the key Full access.

## Change the scope of a key

Send the new scope to `PATCH /api-keys/{api_key_id}`:

```bash cURL theme={null}
curl -X PATCH https://api.platform.dakota.xyz/api-keys/{api_key_id} \
  -H "x-api-key: $DAKOTA_API_KEY" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scope": "operate"}'
```

The change applies from the next request. The key value stays the same, so the integration does not need a new key. Each change sends an `api_key.updated` event, and its `previous_attributes` field holds the old scope.

Only team admins and Full access keys can create, change or revoke keys.

## Keys belong to your organization

A key belongs to your organization, not to the person who created it. The key keeps working after that person leaves your team.

When you remove a team member in the dashboard, the dashboard lists the keys that the person created. Revoke the keys that you no longer need. `DELETE /users/{user_id}` does not revoke them.

When a key creates another key, the `api_key.created` event names the creating key in `created_by_api_key_id`.

## What scopes do not do

* **Keys do not expire.** A key works until you revoke it. Each key shows when it was last used, so you can find the keys that nobody uses.
* **You cannot build your own scope.** Every key has one of the three scopes. If no scope fits your integration, tell your Dakota contact.
* **Scopes do not change team roles.** Admins and Viewers keep the access that they have today, and every admin can see and revoke every key of your team.


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