Get started
Authentication
How calls to the Toku API are authenticated: organization API keys for servers and scripts, and a person's sign-in for the Toku app and AI assistants.
A call to the Toku API is authenticated in one of two ways:
- An organization API key, for a server or script that calls the API with no one signing in. Each key has a permission per area (none, read or write).
- A person's sign-in, for the Toku app and AI assistants. The call can do exactly what that person's seat can do in the Toku app.
Organization API keys#
An admin of your organization creates a key under Settings › Developer › API keys, gives it a
permission per area, and copies it once. It starts with toku_sk_. Send it as a bearer token and
nothing else that identifies you:
The key carries its organization, so a call with a key sends no x-toku-org-id or x-role-type.
Each operation's page in this reference states the Required scope a key needs to call it, for
example people:read, and says when an operation is not available to keys.
The API keys guide shows how to create, roll and revoke a key, lists every area and explains each refusal.
Keys are read-only today and can read every area except token grants and cards (no card operation can be read with a key yet). Write permissions will be switched on area by area. If you don't see Developer in your settings, ask your Toku contact to switch it on for your organization.
A person's sign-in#
The Toku app calls the API for whoever is signed in, and AI assistants such as Claude call it
through the Toku connector at https://api.toku.com/mcp after the person signs in to Toku in their
browser. The Connect Claude to Toku guide shows how.
A call made with a sign-in sends:
| Header | Purpose |
|---|---|
Authorization: Bearer <access token> | Required. An access token from a person's Toku sign-in. |
x-toku-org-id | The organization to act in. Needed when the person has seats in more than one organization. |
x-role-type | The role to act as in that organization, such as CLIENT_ORG_ADMIN. Optional: without it, Toku uses the person's seat in that organization. |
The API checks the organization and role against the person's live seats on every call, so a seat that is removed or changed stops working at once.
Most operations also require a sign-in that proves a second factor: your company's single sign-on,
or two-factor authentication on your Toku login. A sign-in with only a password is answered 403.
Personal tokens from API v1#
The personal tokens created for the API v1 (legacy) work only with that API,
and this API answers them with 401. Use an organization API key instead.