How to make an API key and know what it can do
Make an API key, pick its scopes, and learn its limit, its reach and when it stops.
Browse
On this page
How to do it
Open Settings, then Security, then Access & Sessions. Find the API Keys card.
Press New Key.
Fill in the New Key window.
Type a Name, such as Zapier integration. Pick the Scopes, such as Read tickets, Read clients or Read devices (MSP). Read knowledge base lets a key read one client's pending drafts. It works only if you have Knowledge Base: View. Set Expires if you want an end date. Leave it blank for a key that does not expire. There is no rate limit field and you cannot pick a client for a key.
Press Create Key, then save the key.
The window says Save this key now - it will not be shown again. Press Copy, store it somewhere safe, then press Done - I've saved it.
Know the limit.
Every key gets 1000 requests per hour. The count is per key, across every API route, in a fixed window of one hour. A key that goes over gets the status 429. The Retry-After header tells you how many seconds to wait.
Know what the key can do.
The public API (version 1) reads tickets, their replies and their devices. It also reads clients and devices. Lists come in pages of 25, or up to 100 if you pass limit. An older key limited to one client is refused. The API can make only a few changes today. One is hiding a health issue on a device. When you retry a change, send the same Idempotency-Key. Then it is made once. While the portal is locked for changes, a change through a key is refused and reads keep working.
Know when a key stops working.
If its maker loses a permission, the key loses it on its next request. If the maker's account is turned off, blocked or removed, the key stops working. Make a new key from an active account. To end a key on purpose, press Revoke on the API Keys card. Signing out someone everywhere does not turn off their keys.
What you will have
- Make an API key with New Key.
- Pick scopes that fit the job.
- Know the limit of 1000 requests per hour.
- Know what the key can read and change.
- Know when a key stops working.
Why it works this way: How to make an API key and know what it can do
An API key acts as the person who made it. The portal checks what that person may do on every request.
Scopes only narrow a key. They never give it more than its maker has.
If it did not work: How to make an API key and know what it can do
- You lost the key: it is never shown again. Revoke it and make a new one.
- A call gets 429: wait the seconds in the Retry-After header.
- A call is refused for one client: the public API refuses a key limited to one client.
Questions this page answers
Is there a rate limit on an API key?
Yes. Every key gets 1000 requests per hour, counted per key. A key over the limit gets the status 429 and a Retry-After header.
Does an API key still work if the person who made it loses access?
No. A key acts as its maker. If the maker loses a permission or the account is turned off, the key loses it or stops.
Which scopes can I give an API key?
You pick them when you press New Key, such as Read tickets, Read clients and Read devices (MSP). A scope never gives a key more than its maker may do.
Was this helpful?