Get started

API keys

An API key lets one of your tools use the API on behalf of your workspace. Give each tool its own key with only the access it needs, so you can revoke one without touching the others.

Create a key#

Go to Developers settings
Settings → Developers → API keys, then Create key. You need to manage integrations across the whole workspace (owners and admins do).
Choose live or test
Live works on your real people, sites and hours. Test works on a separate copy with sample data, safe to change (see test keys).
Pick its access and expiry
Tick the scopes it needs. Choose when it expires: never, in 30 days, in 90 days or in a year (the API accepts 1 to 730 days).
Copy it once
The full key is shown only once. ClockLap stores only a hash, so if you lose it, revoke it and create a new one.

A key can never do more than the person who made it can do across the whole workspace. If you can't tick a scope, you don't have that access yourself.

Use a key#

Send it in the Authorization header on every request:

GET /v1/users HTTP/1.1
Host: ca-api.clocklap.com
Authorization: Bearer tt_live_ca_9fK2…

Keys look like tt_live_ca_… or tt_test_us_…: the mode, then the region, then a random part. Call the region in the key. Sent to the other region, a request gets 421 wrong_region with the right api_url in the body.

Scopes#

Scopes decide what a key can do. All keys act on the whole workspace (every location).

Scope	Shown in the console as	Lets the key
`time:read`	Read time entries and timesheets	Shifts, timesheets, live attendance, exceptions. Also reads people and locations, which time refers to.
`time:write`	Create and edit time, approve, punch	Add or fix shifts, approve and lock timesheets, punch on someone’s behalf, resolve exceptions, manage schedules.
`people:read`	Read people	People, their roles, sites and external IDs.
`people:write`	Invite and edit people	Invite, update, archive people and manage roles.
`locations:read`	Read locations and geofences	Regions, sites, zones and their geofences.
`locations:write`	Manage locations and geofences	Create and change locations and geofences.
`reports:read`	Run reports and exports	Hours, overtime and attendance reports, CSV, Excel and PDF exports.
`webhooks:manage`	Manage webhooks and read events	Webhook endpoints, deliveries and the events API.
`projects:write`	Manage clients, projects and activities	Clients (customers), projects and activities with bill rates.
`invoices:write`	Create, send and record payments on invoices	Draft, send and void invoices, record payments.
`admin`	Full access	Everything an owner can do. Use only when nothing narrower works.

A few actions need a signed-in person rather than a key, such as changing a password. Those answer 403 with “This action needs a signed-in user, not an API key”. To punch for someone with a key, send their user_id and source: "api" (time:write).

Test keys#

A test key (tt_test_…) works in a sandbox: a private copy of your workspace's settings, filled with made-up data. It's created the first time you make a test key and contains:

two sites, “Sample Warehouse” and “Sample Store”, each with a 120 m geofence;
six people with @example.test emails and Monday to Friday schedules;
two weeks of shifts, including some missed clock-outs and late arrivals.

Test requests are never billed. Responses carry ClockLap-Mode: test, and webhook events from the sandbox say "livemode": false. Wipe it back to fresh sample data any time with Reset test data in the console or POST /v1/sandbox/reset (keys and webhooks stay).

Keep keys safe#

Server side only. Never put a key in a web page, a mobile app or a public repository.
One key per tool. Name it after the tool, so the console's “last used” tells you what's still in use.
Least access. A reporting tool needs time:read and reports:read, not admin.
Rotate. Create the new key, switch your tool over, then revoke the old one.

Revoke a key#

In the console, open the key and choose Revoke. Anything using it stops working at once (401). With the API: DELETE /v1/api-keys/{id}. Revoked and expired keys stay listed so you can see what happened.

Manage keys with the API#

Endpoint	What it does
`GET /v1/api-keys`	Lists keys with their prefix, scopes, mode and `last_used_at` (never the key itself).
`POST /v1/api-keys`	Creates a key: `name`, `scopes`, `mode` (`live` or `test`), `expires_in_days`. The response has `key`, once.
`DELETE /v1/api-keys/{id}`	Revokes a key.
`GET /v1/permissions`	Every permission, the built-in roles and the scopes a key can have.