Skip to main content
Every API request needs a key. A key proves the request is yours and ties it to one workspace. You make keys in the ZeroRank app, then send one with each request.
Only workspace owners and admins can make or remove keys. A key can read your data and spend your plan usage, so it is kept to those roles.

​
Make a key

1

Open Workspace settings

In ZeroRank, go to Workspace settings and find the API Access card.
2

Click New API key

Give the key a name you will recognize later, like Production server.
3

Choose what it can do

Leave Allow write access on for a key that can change data. Turn it off for a read-only key.
4

Pick when it expires

Choose Never, 30 days, 90 days, or 1 year. The key stops working after that.
5

Copy the key

Click Create key and copy it right away. You will not see the full key again.
The full key is shown once, at creation. Copy it and keep it somewhere safe, like a password manager. If you lose it, make a new one.
Every key looks like zr_live_ followed by a long string of letters and numbers.

​
What a key can do

Each key carries one or both of these scopes (the things it is allowed to do):
  • read — every key has this. It can read your data with GET requests.
  • write — needed to create, update, delete, or run anything.
A read-only key is safe to use where you only need to look at data. A write request with a read-only key gets a 403 reply.
In the app, the Allow write access switch sets this. On gives a read + write key. Off gives a read-only key.

​
Send your key

Put the key in the Authorization header of each request, after the word Bearer.
Keep your key secret, like a password. Do not put it in code you share or in a public place. Use a key with only the access it needs.

​
See and remove keys

The API Access card lists your active keys. For each one you can see its name, scopes, when it was made, and when it was last used. To turn a key off, click the trash icon and confirm. The key stops working right away. Do this if a key leaks or you no longer need it.
A workspace can have up to 25 active keys at once. Remove an old key to make room for a new one.

​
When a request is refused

Check that you sent the Authorization header and that it starts with Bearer . Make sure the key is not removed or expired.
You tried to change data with a read-only key. Make a new key with Allow write access on, or use one you already have.
The API needs a paid plan or an active trial. Check your plan on the billing page. The free tier cannot use the API.
You went over your per-minute limit. Wait the seconds shown in the Retry-After header, then try again. Higher plans get a higher limit.
Still stuck? Email [email protected].

​
Keep going

API overview

The base address, rate limits, and what comes back.

Billing and plans

See which plan you are on and what it includes.