Skip to main content
Every request carries one credential as a Bearer token. Usertick accepts two kinds of credential: The credential determines the organization, so no route contains an organization id.

​
Send the credential

The credential goes in the Authorization header. If a client can’t set that header, it can send the key in X-Api-Key instead. When both headers are present, Authorization takes precedence.
GET /me needs no scope, which makes it the simplest way to check a key. It returns the organization, the key’s name and scopes, and its rate limits.

​
Keys belong to the organization

An API key belongs to your organization instead of the person who created it. The key keeps working when that person leaves the organization or changes role, and the key list still shows who created each key. A key acts as the organization itself:
  • Changes it makes appear in the activity log as via API key followed by the key’s name.
  • A note it writes shows the key’s name as its author.
  • It can do what its scopes allow, in its own organization only.
A key stops working when it is revoked or expires, when the organization is inactive, or when the plan no longer includes the API. In that last case, calls return 403 with APK-004-005, and the key works again after an upgrade.
Treat keys like passwords. Keep them in server side configuration, never in browser code or a repository. If a key leaks, revoke it or rotate it.

​
Create a key

Managing keys requires the Manage developer settings permission. Creating or rotating a key also requires the Pro plan or above.
1

Open the form

Under Settings → Developers → API keys, select Create API key.
2

Name the key

In Name, enter what will use the key, such as “CI export job”.
3

Select its access

Under Access, select only the access the key needs.
4

Choose the expiry

Under Expires, select No expiry, In 30 days, In 90 days, In 1 year or On a date.
5

Copy the key

After you select Create API key, copy the key into your secret store before you select I saved it.
When one kind of access depends on another, the form selects both. A date under On a date can be up to 2 years ahead, and the key works through the end of that day in UTC. The full key is shown only once. Usertick stores only a hash of it, so afterward the dashboard shows only the key’s prefix.

​
Scopes

Each scope has a label in the dashboard, shown under Access. Three endpoints also need responses:read. The first two return response data, and the third lists what a subscription can receive: A call without every scope it needs returns 403 with APK-004-004. Each page in the API reference lists the scopes of its endpoint.

​
Key status

The key list opens with the Status filter set to Active, which also shows rotating keys. Revoked and expired keys stay in the list, so their history remains readable: to see them, open Filters and pick Revoked or Expired, or remove the filter.

​
Rotate a key

To rotate a key, select its row in the key list, select Rotate key and then Rotate now. Usertick shows the new secret once. The old secret keeps working for 24 hours, so the new one can be deployed without downtime. The key keeps its id, name, access, expiry, usage history and webhook subscriptions. Rotating again within those 24 hours ends the older secret immediately. A revoked or expired key can’t be rotated, so a new key has to be created instead.

​
Change a key’s access

To change what a live key can do, select its row in the key list, select Edit access, change the selection and select Save changes. The key uses the new access from its next request. When the key loses webhooks:write or responses:read, every webhook subscription it made stops sending, and the panel says so before you save. A revoked or expired key can’t be changed.

​
Revoke a key

To revoke a key, select its row in the key list, select Revoke key, type the key’s name and confirm. Revoking stops the key immediately, including both secrets during a rotation. Every webhook subscription the key made stops sending. Revoking can’t be undone.

​
Review a key’s usage

When you select a key’s row in the key list, the row opens and shows what the key did:
  • Usage shows the requests per day over the last 30 days, split into Successful (2xx), Client errors (4xx), Rate limited (429) and Server errors (5xx), with the totals for those 30 days above the chart.
  • Recent requests lists the key’s latest 5 calls from the last 7 days, newest first, with the time, method, path, status and duration. Request and response bodies are never kept.
  • Show all opens every call of the last 7 days in a panel, newest first. More calls load as you scroll, and Filters → Status narrows the list to succeeded or failed calls, client errors, rate limited calls or server errors.
When Usertick couldn’t count some of your organization’s calls in the period, a line under the chart says how many. The numbers in Usage can then be lower than the actual use; the calls themselves were answered as usual. A request without a valid key returns 401 and has no key to count toward, so it doesn’t appear in a key’s usage.

​
Apps

Apps that act for other people, such as the Usertick app for Zapier, don’t use API keys. The person approves the app in Usertick, and the app receives an access token. Apps work on the Starter plan and above. See OAuth for apps. Each connection of the Zapier app appears under Connections in Settings → Integrations → Zapier, where a member whose role has the Manage integrations or Manage developer settings permission can select Revoke access.

​
Error codes

A bad credential always returns 401 instead of 403. Every code is listed on the errors page.