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

# Roles & Permissions

> Which API endpoints each role can access

## Overview

Every API request includes an `x-role-type` header that determines what the caller can do. Your API token must belong to a user with the specified role in the organization.

There are three permission levels in the Toku API:

| Level                      | Base Class                 | Who Can Call                                 | Count              |
| -------------------------- | -------------------------- | -------------------------------------------- | ------------------ |
| **Any authenticated user** | `AuthorisedOperation`      | Any user with a valid token + org membership | 36 endpoints (61%) |
| **Admin only**             | `AdminOperation`           | `CLIENT_ORG_ADMIN` or equivalent admin role  | 28 endpoints (38%) |
| **Client Admin only**      | `TokuClientAdminOperation` | `CLIENT_ORG_ADMIN` specifically              | 4 endpoints        |

<Tip>
  **For 3rd party integrations, use `CLIENT_ORG_ADMIN`.** It has access to all 68 public endpoints. Other roles have more limited scope.
</Tip>

***

## Permissions by Endpoint

### Grants (Admin Required)

All grant write operations require admin access.

| Endpoint                         | Method | Permission                  |
| -------------------------------- | ------ | --------------------------- |
| `listGrants`                     | GET    | Admin                       |
| `listGrantConfigurations`        | GET    | Admin                       |
| `getEmployeeGrants`              | GET    | Admin                       |
| `getPayrollEmployeeID`           | GET    | Admin                       |
| `addSingleGrant`                 | POST   | Admin                       |
| `createGrantForNewHire`          | POST   | **CLIENT\_ORG\_ADMIN only** |
| `terminateGrant`                 | POST   | Admin                       |
| `terminateGrants`                | POST   | Admin                       |
| `terminateEmployeeGrants`        | POST   | Admin                       |
| `revertGrantTermination`         | POST   | Admin                       |
| `revertEmployeeGrantTermination` | POST   | Admin                       |
| `revertEmployeeGrants`           | POST   | Admin                       |

### Wallets (Mostly Any Authenticated User)

Most wallet operations are available to any authenticated user — this allows recipients to manage their own wallets.

| Endpoint                           | Method   | Permission |
| ---------------------------------- | -------- | ---------- |
| `getAllWallets`                    | GET      | Any user   |
| `getCurrentWallet`                 | GET      | Any user   |
| `getUserCurrentWallets`            | GET      | Any user   |
| `getHistoricalWallets`             | GET      | Any user   |
| `getAllHistoricalWallets`          | GET      | Any user   |
| `getAllWalletsForAllRecipients`    | GET      | Any user   |
| `getPendingWallets`                | GET      | Any user   |
| `getPendingWalletRequest`          | GET      | Any user   |
| `getTestTxnApprovalPendingWallets` | GET      | Any user   |
| `getOrgWalletInfo`                 | GET      | Any user   |
| `getEmployeeWallets`               | GET      | **Admin**  |
| `getEmployeeHistoricalWallets`     | GET      | **Admin**  |
| `getPendingWalletRequests`         | GET      | **Admin**  |
| `getVerifiedWalletTestRequests`    | GET      | **Admin**  |
| `getPendingWalletTestRequests`     | GET      | **Admin**  |
| `addWallet`                        | POST     | Any user   |
| `updateWallet`                     | POST/PUT | Any user   |
| `markWalletAsNotCurrent`           | POST     | Any user   |
| `reactivateWallet`                 | POST     | Any user   |
| `approveWallet`                    | POST     | Any user   |
| `rejectWallet`                     | POST     | Any user   |
| `approveWalletRequest`             | POST     | Any user   |
| `rejectWalletRequest`              | POST     | Any user   |
| `cancelWalletRequest`              | POST     | Any user   |
| `bulkUploadMultipleWallets`        | POST     | Any user   |
| `addTestTransaction`               | POST     | Any user   |
| `sendTestTransaction`              | POST     | Any user   |
| `addTestTxnToWallet`               | POST     | Any user   |
| `processBulkTestTransactions`      | POST     | Any user   |
| `resendTestTxnEmailToWalletOwner`  | POST     | Any user   |

### Wallet Distribution (Any Authenticated User)

| Endpoint                                  | Method | Permission |
| ----------------------------------------- | ------ | ---------- |
| `getAllWalletReferencesForAllGrants`      | GET    | Any user   |
| `getWalletReferencesWithNetworks`         | GET    | Any user   |
| `configureWalletRefsDistributionForGrant` | POST   | Any user   |
| `setTokenWalletRefsDistribution`          | POST   | Any user   |

### Employees (Admin Required)

| Endpoint               | Method | Permission |
| ---------------------- | ------ | ---------- |
| `getUserRoleInOrg`     | GET    | Admin      |
| `createUserRoleInOrg`  | POST   | Admin      |
| `updateUserRoleInOrg`  | PUT    | Admin      |
| `batchUpdateRoleInOrg` | PUT    | Admin      |

### Tokens & Networks

| Endpoint           | Method | Permission |
| ------------------ | ------ | ---------- |
| `getWalletTypes`   | GET    | Any user   |
| `getTokenTypes`    | GET    | Any user   |
| `getTokenTypesNew` | GET    | Any user   |
| `getNetworks`      | GET    | Any user   |
| `getNetworksNew`   | GET    | Any user   |
| `deleteWalletType` | DELETE | **Admin**  |
| `deleteNetwork`    | DELETE | **Admin**  |

### Invoices (Admin Required)

| Endpoint                      | Method | Permission |
| ----------------------------- | ------ | ---------- |
| `submitBulkInvoicePayments`   | POST   | Admin      |
| `markInvoicePaymentAsSettled` | POST   | Admin      |

### Organization

| Endpoint                             | Method | Permission                  |
| ------------------------------------ | ------ | --------------------------- |
| `hello`                              | GET    | **CLIENT\_ORG\_ADMIN only** |
| `getOrgWalletInfo`                   | GET    | Any user                    |
| `updateOrgTokenAddress`              | POST   | Admin                       |
| `updateTestTransactionConfiguration` | PUT    | Admin                       |

### Authentication (CLIENT\_ORG\_ADMIN Only)

| Endpoint              | Method | Permission                  |
| --------------------- | ------ | --------------------------- |
| `createUserApiToken`  | POST   | **CLIENT\_ORG\_ADMIN only** |
| `refreshUserApiToken` | POST   | **CLIENT\_ORG\_ADMIN only** |
| `generateAuthNonce`   | POST   | Any user                    |

***

## Permission Levels Explained

### Any Authenticated User (`AuthorisedOperation`)

Requires a valid API token and membership in the organization. Any role works — `CLIENT_ORG_ADMIN`, `PAYROLL_ADMIN`, `FINANCE_ADMIN`, `INVESTOR`, or `RECIPIENT`.

### Admin (`AdminOperation`)

Requires `CLIENT_ORG_ADMIN` or another admin-level role (`PAYROLL_ADMIN` for some operations). The exact admin roles accepted vary by endpoint, but `CLIENT_ORG_ADMIN` always works.

### CLIENT\_ORG\_ADMIN Only (`TokuClientAdminOperation`)

Strictly requires the `CLIENT_ORG_ADMIN` role. No other admin role is accepted.

***

## Error When Permission Denied

```json theme={null}
{
  "error": "Invalid token or insufficient permissions",
  "details": "User does not have role CLIENT_ORG_ADMIN in organization aa0e8400-..."
}
```

**Status code:** `403 Forbidden` (role mismatch) or `401 Unauthorized` (invalid token)

***

## Recommendation

For a complete 3rd party integration that manages grants, wallets, and employees, create your API token with **`CLIENT_ORG_ADMIN`**. This is the only role guaranteed to work with all 68 public endpoints.