> ## 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.

# 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:

```bash
curl https://api.toku.com/hris/get-hris-people \
  -H "Authorization: Bearer toku_sk_..."
```

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](/api-reference/guides/api-keys) shows how to create, roll and revoke a key,
lists every area and explains each refusal.

> **Info:** 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](/api-reference/guides/connect-claude) 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)](/api/authentication) work only with that API,
and this API answers them with `401`. Use an organization API key instead.
