> ## 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 with API keys

> Mint an organization API key with a permission per area, and call the Toku API with it.

An API key lets a server or script call the Toku API for your organization without anyone signing
in. Each key has a permission per area (None, Read or Write), like a Stripe restricted key, and every
call is checked against it.

## Mint a key

1. Sign in to Toku as a full client admin of your organization.
2. Open **Settings › Developer › API keys** and choose **Create key**. (If you don't see Developer,
   ask your Toku contact to switch it on for your organization.)
3. Name the key, pick a lifetime (7, 30, 60 or 90 days, a date up to a year away, or no expiry) and
   set each area to **None**, **Read** or **Write** (Write shows "Coming soon" until it is switched
   on for that area). You can only grant what your own page access in Toku allows.
4. Copy the key. It starts with `toku_sk_` and is shown once.

Every full client admin of your organization sees, edits, rolls and revokes the organization's keys.
**Roll** issues a new secret with the same name and permissions and keeps the old one working for the
grace period you choose. **Revoke** stops a key at once.

A key acts through its owner's admin seat. If that seat is removed, deactivated or narrowed to a team,
the key stops working until another admin takes ownership of it.

## Call the API

Send the key 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: don't send `x-toku-org-id`, `x-role-type` or a personal-token
  header. A call with an identity, organization, role or acting header is refused.
- Send the key only in `Authorization`. A key in a query string or any other header is refused, and
  so is a key sent to a public (no sign-in) endpoint.
- A key can call every operation whose reference page states a **Required scope** its scopes grant,
  whether Toku serves it natively or carries it to its older app on the owner's behalf.
- Over MCP (the Claude connector), a key reaches the reads in the connector's catalog that its scopes
  grant, such as `list_people`, `list_org_time_off` and `list_org_payslips`. The `discover` tool lists
  exactly the tools the key can call. Writes over MCP are not available to keys yet.
- A key has no person of its own. An operation that would otherwise act on "the signed-in person"
  when you leave out whom it is for (for example `roleInOrgID` on
  `GET /hris/get-hris-employee-leave-balance`) needs that field with a key; its reference page says so.

## Scopes

A scope is `<area>:read` or `<area>:write`, and write includes read for the same area. Each operation
in this reference that a key can call states its **Required scope**, for example `people:read`, and
carries it as `x-toku-required-scope` in `openapi.yaml`. A few also need a scope that depends on the
request, such as a report's own area for `POST /hris/generate-report`, and their page lists it.
A read that includes several areas needs every listed scope, and its owner must hold the page access
for each area. Toku checks those rights again when the call is carried to the older app.
Operations marked "Not available to API keys yet" will open with the scope they name (a write, or a
`grants` read), and those marked "Not available to API keys." can't be called with a key.

| Area           | What it covers                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `people`       | Employees, contractors and invites: profiles, onboarding progress, reporting lines, change requests and offboarding.   |
| `compensation` | Salaries and their history, additional and statutory pay, payslips and salary-linked reports.                          |
| `banking`      | Bank and payout details: company bank accounts, contractors' payment methods and people's payout wallets.              |
| `identity`     | I-9 and E-Verify records and the company's business verification.                                                      |
| `time`         | Time off, leave types and balances, company holidays, timesheets and time-tracking rules.                              |
| `expenses`     | Expense reports, receipts, categories, spending caps and expense approvals.                                            |
| `documents`    | Employee and company documents, templates, e-signature and benefits enrollment.                                        |
| `payroll`      | Payroll runs and approvals, tax profiles, payroll entities and settings, stablecoin and token payroll.                 |
| `payments`     | Payment batches, payouts, invoice payments and settlements.                                                            |
| `invoices`     | Contractor invoices: creating, reviewing and approving them, and auto-invoicing.                                       |
| `grants`       | Token and equity grants, vesting and lockups, warrants and investors, exercises and staking.                           |
| `wallets`      | Company and custody wallets, custody allocations, networks, tokens and test transactions.                              |
| `cards`        | The company view of contractor Toku cards.                                                                             |
| `reports`      | Reports, dashboards and CSV exports.                                                                                   |
| `organization` | Company profile and settings, modules, notification policy and setup status.                                           |
| `integrations` | Connected services (ADP, UKG, Workday, QuickBooks, Greenhouse, Airwallex, Fireblocks and more), without their secrets. |

Keys are read-only today, and an area can be granted only once it has a read a key can call, so the
`grants` area can't be granted yet. Write scopes will be switched on area by area, with the areas
that move money or crypto (expenses, payroll, payments, invoices, grants, wallets, cards, banking and
integrations) last.

Some operations are never available to a key, whatever its scopes: Toku staff operations, anything
that acts on a signed-in person's own account (their profile, password, two-factor, wallets or
payouts), API key and integration credential management, changes to who can do what (roles,
permissions, approvers, auto-approval, signatories), changes to where a person or the company is
paid, links meant for a person to open in a browser, data deletion requests, and emails to addresses
the call names.

## Refusals

Refusals are JSON. The stable `code`, and any fields it comes with, are under `details`:

```json
{ "details": { "code": "insufficient_scope", "required_scope": "time:read", "granted_scopes": ["people:read"] } }
```

| Status | `code`                       | Meaning                                                                                                                                                               |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `invalid_api_key`            | The key is unknown, malformed, revoked or expired, or it was rolled and its grace has ended.                                                                          |
| 403    | `insufficient_scope`         | The key lacks the scope this call needs. `details` names `required_scope` and the key's `granted_scopes`.                                                             |
| 403    | `not_available_to_api_keys`  | The operation is not open to keys. `reason` is `not_in_key_surface`, or `not_native_yet` when this deployment cannot yet carry a key to the operation.                |
| 404    |                              | No operation lives at that path: an unknown path, or a known one with a trailing slash or in another case.                                                            |
| 403    | `api_key_owner_inactive`     | The key's owner can no longer act for it (no longer an organization-wide admin, or their sign-in is blocked). Another admin can take ownership in Developer settings. |
| 403    | `api_key_permission_missing` | The key's owner no longer has the admin page access this area needs (view to read, full to write). `details` names the `area`.                                        |
| 403    | `developer_settings_off`     | Developer settings are turned off for the organization.                                                                                                               |
| 403    | `api_key_header_refused`     | The request sent a header that cannot go with a key, such as an organization, role or personal-token header. `details` names the `header`.                            |
| 403    | `api_key_misplaced`          | A key was sent anywhere but `Authorization: Bearer`, such as another header or the query string.                                                                      |
| 400    | `api_key_target_required`    | The operation needs to know whom it is for, and a key has no person of its own. `details` names the `field` to fill.                                                  |
| 429    |                              | Too many requests for this key.                                                                                                                                       |

A call Toku carries to its older app on the key owner's behalf can also be refused there, by that app's own checks on
the owner's access. That refusal arrives as a `403` with the older app's message and no `code`.
