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#

  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:

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.

AreaWhat it covers
peopleEmployees, contractors and invites: profiles, onboarding progress, reporting lines, change requests and offboarding.
compensationSalaries and their history, additional and statutory pay, payslips and salary-linked reports.
bankingBank and payout details: company bank accounts, contractors' payment methods and people's payout wallets.
identityI-9 and E-Verify records and the company's business verification.
timeTime off, leave types and balances, company holidays, timesheets and time-tracking rules.
expensesExpense reports, receipts, categories, spending caps and expense approvals.
documentsEmployee and company documents, templates, e-signature and benefits enrollment.
payrollPayroll runs and approvals, tax profiles, payroll entities and settings, stablecoin and token payroll.
paymentsPayment batches, payouts, invoice payments and settlements.
invoicesContractor invoices: creating, reviewing and approving them, and auto-invoicing.
grantsToken and equity grants, vesting and lockups, warrants and investors, exercises and staking.
walletsCompany and custody wallets, custody allocations, networks, tokens and test transactions.
cardsThe company view of contractor Toku cards.
reportsReports, dashboards and CSV exports.
organizationCompany profile and settings, modules, notification policy and setup status.
integrationsConnected 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:

{ "details": { "code": "insufficient_scope", "required_scope": "time:read", "granted_scopes": ["people:read"] } }
StatuscodeMeaning
401invalid_api_keyThe key is unknown, malformed, revoked or expired, or it was rolled and its grace has ended.
403insufficient_scopeThe key lacks the scope this call needs. details names required_scope and the key's granted_scopes.
403not_available_to_api_keysThe 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.
404No operation lives at that path: an unknown path, or a known one with a trailing slash or in another case.
403api_key_owner_inactiveThe 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.
403api_key_permission_missingThe key's owner no longer has the admin page access this area needs (view to read, full to write). details names the area.
403developer_settings_offDeveloper settings are turned off for the organization.
403api_key_header_refusedThe request sent a header that cannot go with a key, such as an organization, role or personal-token header. details names the header.
403api_key_misplacedA key was sent anywhere but Authorization: Bearer, such as another header or the query string.
400api_key_target_requiredThe operation needs to know whom it is for, and a key has no person of its own. details names the field to fill.
429Too 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.

Was this page helpful? Suggest edits