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:
For 3rd party integrations, use CLIENT_ORG_ADMIN. It has access to all 68 public endpoints. Other roles have more limited scope.
Permissions by Endpoint
Grants (Admin Required)
All grant write operations require admin access.
Wallets (Mostly Any Authenticated User)
Most wallet operations are available to any authenticated user — this allows recipients to manage their own wallets.
Wallet Distribution (Any Authenticated User)
Employees (Admin Required)
Tokens & Networks
Invoices (Admin Required)
Organization
Authentication (CLIENT_ORG_ADMIN Only)
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
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.