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:

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

HeaderPurpose
Authorization: Bearer <access token>Required. An access token from a person's Toku sign-in.
x-toku-org-idThe organization to act in. Needed when the person has seats in more than one organization.
x-role-typeThe 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.

Was this page helpful? Suggest edits