Settings & Admin

API Keys and Logs

Switch API access on for a client account, make one key per system with only the access it needs, rotate and revoke keys, and check every request in the API logs.

Talk to us Browse all guides

Last checked against the product:

Overview Who Does What Switch API Access On Create a Key Access Levels Expiry, Limits, Sites, Origins Change a Key Rotate a Key Revoke a Key API Logs Agency Console Limits Troubleshooting Related Guides

Overview

One key per system, each with only the access it needs.

Before you start

  • Agency console (to switch API access on): an Admin with the API Management page, or a super admin (Setup > Users).
  • Client dashboard (to make and manage keys): an Admin user. Managers and Viewers do not see Setup > API keys or Setup > API logs.
  • API access switched on for the client account by the agency. Until then both client dashboard pages show API Access Not Available.
  • A safe place to keep the key in the other system (its secret store or settings). A key is shown once only.

An API key lets another system (payroll, an ATS, a reporting tool, a site screen) read or change one client account's data in TempClock. Each key belongs to one client account and sees every site of that account. TempClock keeps only a fingerprint of the key, so a lost key cannot be shown again: rotate it or make a new one.

Who Does What

The agency opens the door; the client's own admins manage the keys.

Task Where Who
Switch API access on or off for a client account Agency console: Setup > API Admin with the API Management page, or a super admin
Create, change, rotate and revoke keys for your own account Client dashboard: Setup > API keys Admin
See every request made with your keys Client dashboard: Setup > API logs Admin
Create and manage keys for any client account Agency console: Setup > API Admin with the API Management page, or a super admin
Give a key Payroll, Pay or Charges access Either key screen Someone with the See pay rates and pay totals permission
Give a key Set rates Either key screen Someone with the Change pay and charge rates permission
Set a rate limit above 120 requests a minute Agency console: Setup > API Super admin only (up to 600)
Note

A client dashboard Admin always holds both pay permissions, so in the client dashboard every area can be given. In the agency console an Admin whose pay permissions have been unticked sees those areas as No access with "Needs the 'See pay rates and pay totals' permission to give." They can still remove that access from a key, but cannot add or widen it.

Switch API Access On

Once per client account, in the agency console.

Open Setup > API

In the agency console go to Setup > API. The Client API Access table lists every client account with API Enabled, its number of keys and its requests in the last 30 days.

Enable the account

Click Enable on the client's row and confirm. The account's Admins can now use Setup > API keys and Setup > API logs in the client dashboard, and the account appears in the Client list of Generate API Key for Client.

Important

Disable switches API access off and deactivates every key of the account at once: they show as Revoked and answer 401 key_revoked. Webhook subscriptions made with those keys stop receiving events. Enabling the account again does not bring the old keys back: make new ones.

Create a Key

Client dashboard: Setup > API keys.

Open the form

Go to Setup > API keys. The Create an API key form is at the top, above your list of keys.

Name the key

In Key name enter the system that will use it, for example Payroll integration or North depot site screen (up to 100 characters). One key per system means you can revoke one without stopping the others.

Choose what it can do

Under What this key can do pick a level for each area: No access, Read only, Read and write or, for an action, Allowed. See Access levels. A key needs access to at least one area.

Set the extras if needed

Open Expiry, rate limit, sites and browser origins only if the key needs an end date, a higher rate limit or a browser origin. See Expiry, rate limit, sites and browser origins.

Create and copy

Click Create key. A green box headed New API key shows the full key once, with "Copy this key now and store it somewhere safe. It will not be shown again." Put it into the other system straight away.

Important

The form starts with Read only on Workers, Timesheets, Payroll, Shifts, Locations, Departments, Cost codes and Webhooks, and No access on the rest. Payroll includes pay, so set it to No access for a system that does not need pay data.

The page also has a Using Your API Key section with your Base URL and a test call. The test call (me.php) answers which account and sites the key sees, what it may do, its rate limit and its expiry. Developers send the key in the Authorization: Bearer header.

Access Levels

Give each system only what it needs. Write includes read.

Area What it opens Levels Needs this permission to give
Workers Worker records. Seeing pay and charge rates needs the Pay and Charges scopes. Read only: list and view workers.
Read and write: also create and update workers. Setting or clearing pay and charge rates (hourly_rate, charge_rate) also needs the Set rates scope, rates:write.
Timesheets Clock records with approval status and paid minutes, plus who is on site now. Read only
Payroll Approved, priced hours per worker per pay week, split by pay element. Includes pay. Read only See pay rates and pay totals
Pay Pay rates, pay amounts and pay elements wherever a resource shows them. Read only See pay rates and pay totals
Charges Charge rates, charge amounts and billing fields (PO, Sage account, VAT). Read only See pay rates and pay totals
Set rates Set or clear pay and charge rates on worker records. Allowed Change pay and charge rates
Shifts Scheduled shifts and open demand. Read only: list and view shifts, open demand and offers.
Read and write: also book, change and cancel shifts and add open demand.
On site now Who is on site right now (no pay data). Read only
Locations Sites and their geofence settings. Read only
Departments Department list. Read only
Cost codes Cost code list. Read only
Availability Worker availability rules, and who is free for a time. Read only: list availability rules and see who is free.
Read and write: also add and retire availability rules.
Absences Holiday and sickness requests. Read only
Clock in/out Clock workers in and out from another system. Allowed
Webhooks Webhook subscriptions. Read only: list subscriptions, the event list and the delivery log.
Read and write: also create, change, delete and test subscriptions and rotate the signing secret.
Payroll includes pay: a key with Payroll can read pay rates and amounts even when Pay is set to No access.
Rates need Pay and Charges: without them, worker records come back without their pay and charge rates, and timesheets cannot include pricing.
Typical keys: a payroll import needs Payroll read only. A site screen needs On site now only. An ATS that adds workers needs Workers read and write, without Set rates. A reporting tool rarely needs Pay or Charges.
A request outside the key's access is refused with 403 insufficient_scope, and the reply names the access it needed.

Expiry, Rate Limit, Sites and Browser Origins

Under Expiry, rate limit, sites and browser origins on the form.

Setting What it does Rules
Expiry date (optional) The key stops working at the end of this day, for example a key for a one-off data migration. Leave it empty for no expiry. Today or later, at most 3 years ahead. To stop a key now, revoke it.
Rate limit (requests per minute) How many requests the key may make in one minute. Raise it for a busy system such as a clock feed. 60 by default. 60 to 120 for Admins in either console; a super admin in the agency console can set up to 600.
Sites A key sees every site of its client account. Limiting a key to some sites is not available yet, so the form has no site choice. The key list shows Every site.
Browser origins (optional) Only needed when a web page calls the API straight from the browser. Enter the page's address, for example https://reports.example.com, one per line. Up to 10. https only (http is allowed for localhost). Leave it empty for server to server use, which is recommended.

The key list shows these settings under each key, for example "60 requests a minute. Every site." The Status column shows Active, Active until a date, Rotated, works until a date and time, Expired or Revoked.

Change a Key

Access and settings change without a new secret.

In the Access column, open Edit access under the key, change the levels or settings, and click Save access. The change applies to the key's next request. Every change is written to the audit log with the values before and after (never the key itself).

Edit access and Rotate are only shown for a key still in use. An expired, rotated or revoked key cannot be changed, so an old secret can never be brought back.
Keys made before access levels existed show as Legacy key, fixed to the access they always had (the v1.1 set). Use Edit access to give them a smaller, explicit set.
Agency console: if a key holds access you cannot give (for example Payroll without the pay permission), its Expiry date (optional) and Browser origins (optional) are greyed out with "Only someone who has it can change the expiry date, sites or browser origins." You can still change its rate limit, and you can remove that access but not add it.
Removing an area also stops webhook events that need it: a subscription made with the key only receives events its key can still read.

Rotate a Key

A new secret without downtime.

Open Rotate

In the Actions column, open Rotate on the key. Choose how long the old key keeps working: No overlap (stops now), 1, 3, 7 (the default), 14 or 30 days. Click Rotate key.

Copy the new key

The new key is shown once, with the same name, access and settings. An expiry date carries over: rotating never extends a key. The message says until when the old key keeps working.

Swap it in before the overlap ends

Put the new key into the other system. The old key shows Rotated, works until that time, then stops by itself and answers 401 key_expired.

Make webhook subscriptions again

Webhook subscriptions made with the old key stop when it expires. Create them again with the new key before then. Each new subscription gets a new signing secret, so update the receiver too.

Note

Rotating hands out a new secret, so it follows the same rule as a new key: rotating a key with Payroll, Pay, Charges or Set rates access needs the matching permission.

Revoke a Key

Stop a key at once.

Click Revoke on the key and confirm. In the client dashboard the message is "Revoke this API key? Anything using it stops working straight away." Anything using the key is refused from the next request with 401 key_revoked, and webhook subscriptions made with it stop. Revoking cannot be undone. Revoke a key when the system is retired, when someone who knew it leaves, or if it may have leaked; then create a new one.

API Logs

Client dashboard: Setup > API logs. Every request made with your keys, including refused ones.

The cards at the top count Requests Today, This Week and This Month, and show the Avg Response Time. Each row of the log shows Date / Time, Method, Endpoint, Status, Error (the error_code), IP Address, Response Time and Request ID, newest first, 50 to a page.

Filter the log

Use From and To for dates, Endpoint for part of a path (for example /workers), Status Code and Key, then click Filter. Clear removes the filters.

Find problems

Set Status Code to Any failure, Refused key or access (401, 403) or Rate limited (429), and pick one key in Key. To find a request a developer reports, filter by its time and endpoint and match the Request ID.

Good to know

A key that is not recognised at all (a typo, or a key cut off when it was copied) cannot be tied to your account, so it is not in the log. If it starts like one of your keys, an amber Refused keys that look like yours (last 7 days) panel lists it with the number of refusals, the time and the address.

In the Agency Console

Setup > API covers every client account.

Section What it does
Summary cards Clients with API, Active API Keys, Requests Today and Requests (30 days) across every account.
Generate API Key for Client Make a key for a client account that has API access: choose the Client, enter the Key Name, set What this key can do and the extras, and click Generate Key. The key is shown once; send it to the client securely. The same pay permission rules apply.
Client API Access Switch API access on or off per client account (Enable or Disable). The Keys number opens that client's keys.
API Keys Every key of every account, with Filter by client:. Each row has the access, settings, Created, Last Used and Status, with Edit access, Rotate and Revoke as in the client dashboard.
Refused sign-ins Unknown API keys in the last 24 hours, by address, with Refused, Throttled, Last key tried and Last seen. Revoked and expired keys are in each client's API logs instead.
Top API Consumers The client accounts that made the most requests in the last 30 days.

Limits

What the API enforces.

Limit Value
Requests per key 60 a minute by default; 60 to 120 for an Admin to set, up to 600 by a super admin in the agency console. Over the limit the API answers 429 with a Retry-After header.
Unknown keys from one address An address that sends 20 unknown keys in 5 minutes is refused with 429 for any key that does not work until the count drops. A key that works from the same address is not held back.
Expiry date At most 3 years ahead. The key stops at the end of that day.
Browser origins Up to 10 per key, https only (http for localhost).
Rotation overlap No overlap, or 1, 3, 7, 14 or 30 days.
What a key sees One client account and every site of it. A key covering some sites only, or several client accounts, is not available.

Troubleshooting

The common refusals and what to do.

What you see Why What to do
API Access Not Available on Setup > API keys The agency has not switched API access on for your account, or has switched it off. Ask the agency to enable it on Setup > API in the agency console.
401 invalid_api_key The key is not recognised: mistyped, or cut off when it was copied. Copy the whole key again. If it is lost, rotate the key or make a new one. Check Refused keys that look like yours (last 7 days).
401 key_revoked The key was revoked, or the agency switched API access off for the account. Make a new key (after the agency enables the account again, if needed).
401 key_expired The expiry date has passed, or the overlap after a rotation has ended. Use the new key from the rotation, or make a new key.
403 insufficient_scope The key does not have the access this request needs. The reply names it in required_scope. Open Edit access and give the key that area, if it should have it.
429 with Retry-After The key went over its rate limit, or the address sent too many unknown keys. Wait the number of seconds in Retry-After. Raise the key's Rate limit (requests per minute) if the system is busy all the time.
A web page cannot call the API (blocked by the browser) The page's address is not one of the key's browser origins. Add it under Browser origins (optional), or call the API from a server instead.
"You cannot give a key ... access: it needs the ... permission" Agency console: your user lacks See pay rates and pay totals or Change pay and charge rates. Ask an administrator who has it, or leave that area at No access.
The Rate limit (requests per minute) box will not take more than 120 (its hint says "60 to 120 (up to 600 on request)") Only a super admin can set more than 120. Ask a super admin in the agency console to set up to 600.
"Limiting a key to some sites is not available yet." Site limits are not available on this build. Let the key see every site.
"This key has expired or been rotated, so it can no longer be changed." Old keys cannot be edited or brought back. Change the new key from the rotation, or make a new key.
Getting Started with the API
Setting Up Webhooks
User Roles and Permissions
Developer documentation: authentication and scopes
Developer documentation: error codes
Previous Setting Up Webhooks Next User Roles and Permissions
Back to Support Centre

Know who turned up, and pay every hour right.

Face-verified clock-ins, live geofencing and payroll-ready timesheets in one system. Tell us how your shifts run and we will show you how it fits.

Tell us about your sites See every feature

Hosted in the EU · Your largest site live first, with us alongside · No app needed to clock in