Authentication
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#
- Sign in to Toku as a full client admin of your organization.
- 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.)
- 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.
- 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:
- The key carries its organization: don't send
x-toku-org-id,x-role-typeor 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_offandlist_org_payslips. Thediscovertool 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
roleInOrgIDonGET /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:
| 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.