Authentication

Every request carries a key in an Authorization header:

Authorization: Bearer kitset_sk_live_YOUR_KEY_ID_HERE

There is no other way in. The API does not read cookies, so a browser signed in to the Management Console cannot reach it by navigating to a URL, and no session token from the console will work here. A session belongs to a person; a key belongs to a workspace, and it keeps working after the administrator who created it has left.

What a key looks like

kitset_sk_<environment>_<key id>_<secret>

The key id is public. It appears in your rate-limit responses and in the workspace audit trail, and it is shown beside the key in the console — so when you find a request you did not expect, you can match it to a key without knowing the secret. The secret is stored only as a hash. Nobody at kitset can read it back to you.

The environment is live or test, fixed when the key is created. A key from one will not authenticate against the other, so a credential restored from a staging backup into production fails loudly rather than quietly reading the wrong workspace.

Scopes

A key reaches only what its scopes name. Each :read scope reads one register. The one write scope, kpi:record, records KPI results and reads nothing: an integration that also needs to read KPIs holds kpi:read as well. Grant the fewest an integration needs — a sync that mirrors laptops has no reason to hold people:read.

Scope	Covers	Access	What it allows
`vendors:read`	Vendors & Renewals	Read	Subscriptions, their owners, spend, seats, renewal dates and notice periods.
`approvals:read`	Requests & Approvals	Read	Purchase requests, their approvers and the decisions taken on them.
`systems:read`	Systems & Access	Read	Business systems, their owners and access-review dates.
`learning:read`	Learning & Compliance	Read	Assignments: who was given which content, and their progress, score and completion.
`handovers:read`	Handover & Continuity	Read	Holiday, shift and role handovers: who handed over to whom, when, and their status.
`transitions:read`	Employee Transitions	Read	Joiner and leaver checklists: who each is for, who coordinates it, its dates and status.
`assets:read`	Assets & Maintenance	Read	Equipment, who holds it now, and its warranty and maintenance dates.
`workplace:read`	Workplace Operations	Read	Workplace records and the people they concern.
`people:read`	People	Read	The employee directory: names, work contact details, roles and teams.
`locations:read`	Locations	Read	Sites, departments and teams.
`tasks:read`	Tasks	Read	The shared task list: work generated by handovers and learning assignments, and work people have written by hand.
`kpi:read`	KPI Scorecards	Read	KPI definitions, targets and owners, and each closed period's recorded result.
`kpi:record`	Record KPI results	Write	Record or correct a closed period's result for any active KPI. Write only: reading needs kpi:read as well.

A key may hold a scope for a module the workspace has not installed; a read will simply return nothing, because there is nothing to return. A write is refused with 403 until the app is installed, as it would be for a person in the console.

Ask the API what a key holds:

curl https://your-workspace.kitset.io/api/v1/scopes \
  -H "Authorization: Bearer kitset_sk_live_YOUR_KEY_ID_HERE"

Refusals

401 means the key was not accepted. Every reason gives the same answer — unknown key, wrong secret, revoked, expired, or a token from the other environment. That is deliberate: distinguishing them would tell somebody testing stolen credentials which of them were real.

403 means the key is valid and does not hold the scope that endpoint needs. The message names the scope.

Looking after a key

Keys expire. You choose the life when you create one, up to a year, and ninety days is the default — a key nobody rotates is a key nobody notices has leaked.

Rotating is create, deploy, revoke. The two keys overlap for as long as you need, and revoking does not count against your plan's limit, so rotation never costs you a slot.

If a key leaks, revoke it in the console. It stops on the next request. Then create a replacement — there is no way to change a key's secret while keeping the key.

A key belongs on a server. Not in a browser, not in a mobile application, not in a repository, and not in a support ticket.