Authentication
Every call to the API carries an API key. There is no other way in, and no endpoint works without one.
A key belongs to the account, not to the person who made it. It keeps working when that person changes role or leaves the company. You make keys in the dashboard, and the API reads them on every call.
An SDK key is not an API key
Your account has two kinds of key. Mixing them up is the most common first mistake.
| SDK key | API key | |
|---|---|---|
| What it is for | Telling the script on your site which project it belongs to | Proving who is calling the API |
| Is it secret? | No. It is in your page source. | Yes. Keep it on your server. |
| Where you find it | The install tag, and sdk_key on a project | Settings > API keys |
An API key starts with ss_live_. If a key starts with that, it is a
secret. It does not belong in a browser, a mobile app, a public repository, or
anything a visitor can view the source of.
What a key can do
A key has one of three roles. You choose it when you make the key, and it never changes.
| Role | Read | Create, change and delete |
|---|---|---|
| Viewer | Yes | No |
| Editor | Yes | Yes |
| Publisher | Yes | Yes |
Today a Publisher key can do exactly what an Editor key can. The Publisher role is there for starting and stopping tests, which the API does not do yet.
There is no Admin key. The settings an admin controls in the dashboard stay with people, so a leaked key can never change them.
How to set one up
You need the Admin or Owner role on the account. Everyone else can see the screen but cannot make or revoke keys.
- In the dashboard, open Settings, then API keys.
- Under New key, type a Name.
- Choose What it can do.
- Choose a Project.
- Choose when it Expires.
- Click Create key.
- Copy the key from Your new key and put it in your secret store.
The key is shown once. We keep only a fingerprint of it, so it cannot be shown again or recovered. If you lose it, revoke it and make a new one.
Under the key, Try it shows a ready curl call to /v1/projects. Run it to check
the key works.
What each label means
| Label | What it does | Choices |
|---|---|---|
| Name | What the key is called in the list and in the audit log. Name it for what uses it, such as "Release pipeline". | Up to 120 characters. Required. |
| What it can do | The key's role. See What a key can do. | Viewer, Editor, Publisher |
| Project | Which project the key can reach. A call to any other project answers 404. | One of your projects, or Every project |
| Expires | When the key stops working on its own. | Never, In 30 days, In 90 days, In 365 days |
The Keys list below the form shows each key by its first characters, for
example ss_live_9fQ2xa. That is all of the key we kept. The list also
shows who made each key, its project, when it was last used and when it
expires.
Using a key
Send the key in the Authorization header, as a bearer token:
curl https://api.splitstat.com/v1/projects \
-H "Authorization: Bearer ss_live_your_key_here"
The header is the only place a key is read. There is no query string option, because a key in an address ends up in access logs and browser history.
When a key stops working
| What happened | What a call answers | Can it come back? |
|---|---|---|
| You revoked it | 401 unauthenticated | No. Make a new key. |
| It reached its expiry date | 401 unauthenticated | No. Make a new key. |
| The account's plan has no API access | 403 feature_unavailable | Yes, when the plan includes it again. |
Every bad key answers the same 401, whether it is wrong, revoked or expired.
We do not say which, because that only helps someone who should not have the
key. If a call that worked yesterday answers 401 today, look at the key in
Settings > API keys. The list marks it Revoked or Expired.
Good to know
- Revoking cannot be undone. It takes effect on the next call.
- You can revoke a key even when your plan no longer includes the API.
- A revoked key stays in the list, greyed out, for a week. Then it is hidden.
- Making and revoking a key are both recorded in the audit log, with who did it.
- Last used updates at most once a minute, so a busy key may show a time up to a minute old.
- Give each system its own key. Then revoking one stops nothing else.
- Choose one project unless the key really needs every project. A leaked key then reaches less.
- Set an expiry on any key for a one-off job, such as a data migration.
Related articles
- Introduction: the base address, how responses look, errors and rate limits.
- API reference: every endpoint, with its fields and an example response.