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 reads only what its scopes name. Grant the fewest an integration needs — a sync that mirrors laptops has no reason to hold people:read.

Scope	Covers	What it reads
`vendors:read`	Vendors & Renewals	Subscriptions, contracts, owners, spend, seats and renewal dates.
`approvals:read`	Requests & Approvals	Purchase requests, their approvers and the decisions taken on them.
`systems:read`	Systems & Access	Business systems, their owners and who holds access to each.
`learning:read`	Learning & Compliance	Published content, assignments and acknowledgement evidence.
`handovers:read`	Handover & Continuity	Holiday, shift and role handovers with their items and recipients.
`transitions:read`	Employee Transitions	Joiner and leaver checklists and what each person still holds.
`assets:read`	Assets & Maintenance	Equipment, assignments, custody history and warranty dates.
`workplace:read`	Workplace Operations	Workplace records and the people they concern.
`people:read`	People	The employee directory: names, work contact details, roles and teams.
`locations:read`	Locations	Sites, departments and teams.
`tasks:read`	Tasks	Work generated by handovers and learning assignments.

A key may hold a scope for a module the workspace has not installed; the endpoint will simply return nothing, because there is nothing to return.

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.