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

# Scopes and Permissions

> API credential categories and fine-grained permission scopes.

The Simply Tokenized API uses a two-level permission model.

## Level 1 — Credential categories

When an API credential is created in the Asset Manager dashboard, it is assigned one or more **categories**:

| Category    | Description                             |
| ----------- | --------------------------------------- |
| `OFFERINGS` | Read offering data                      |
| `ACCOUNT`   | Create, read, and update accounts       |
| `ORDER`     | Create, read, update, and cancel orders |
| `WALLET`    | Read wallets                            |

Categories define the **maximum** permissions available to that credential.

## Level 2 — Fine-grained scopes

At authentication time, request specific **scopes** in the `scopes` array. Only scopes allowed by the credential's categories are granted.

| Category    | Available scopes                                             |
| ----------- | ------------------------------------------------------------ |
| `OFFERINGS` | `offering.read`                                              |
| `ACCOUNT`   | `account.create`, `account.read`, `account.update`           |
| `WALLET`    | `wallet.read`                                                |
| `ORDER`     | `order.create`, `order.read`, `order.update`, `order.delete` |

## Endpoint → scope mapping

| Endpoint                                                     | Required scope   |
| ------------------------------------------------------------ | ---------------- |
| `GET /_api/offerings`                                        | `offering.read`  |
| `GET /_api/offerings/{offeringId}`                           | `offering.read`  |
| `POST /_api/offerings/{offeringId}/orders`                   | `order.create`   |
| `GET /_api/offerings/{offeringId}/orders`                    | `order.read`     |
| `GET /_api/offerings/{offeringId}/orders/{orderId}`          | `order.read`     |
| `PATCH /_api/offerings/{offeringId}/orders/{orderId}/cancel` | `order.update`   |
| `POST /_api/accounts`                                        | `account.create` |
| `GET /_api/accounts/{accountId}`                             | `account.read`   |
| `PATCH /_api/accounts/{accountId}`                           | `account.update` |
| `GET /_api/accounts/{accountId}/orders`                      | `order.read`     |
| `GET /_api/accounts/{accountId}/transactions`                | `account.read`   |
| `GET /_api/accounts/{accountId}/benefiting-persons`          | `account.read`   |
| `POST /_api/accounts/{accountId}/benefiting-persons`         | `account.create` |
| `GET /_api/accounts/{accountId}/wallets`                     | `wallet.read`    |
| `GET /_api/accounts/{accountId}/wallets/{walletId}`          | `wallet.read`    |
| `GET /_api/accounts/{accountId}/wallets/balances`            | `wallet.read`    |

## Insufficient scope error

If the token lacks a required scope:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_scope",
    "message": "One or more requested scopes are not allowed for this API credential."
  }
}
```

HTTP status: **403 Forbidden**

## Best practices

* Request the minimum scopes needed for your integration
* Use separate credentials for read-only vs write operations when possible
* Re-authenticate with expanded scopes if your integration requirements change