API keys
This page explains how to create, use, revoke and protect your API keys.
How do I send my API key?
Section titled “How do I send my API key?”Send the key with every request, as a bearer token in the Authorization header:
curl \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/pingThe API takes your firm and your user from the key. You never send a firm id or a user id. A request that names a different firm or user is refused.
What does an API key look like?
Section titled “What does an API key look like?”An API key looks like this example:
sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEYA real key starts with sdeu_key and an underscore. Then come 43 random characters: letters, digits, - and _. The fixed start helps secret scanners find a key that was published by mistake, for example in a code repository.
Whose data can a key read?
Section titled “Whose data can a key read?”A key belongs to one user in one firm. It can read what that user can see in SuperDocs, and nothing more.
- A firm admin can see every case in the firm, so a firm admin’s key can too.
- Other users see only the cases that are shared with them. Their keys see the same cases.
- The API checks the user’s access on every request. If the user’s access to a case changes, the key follows the change.
Only users of a firm can hold a key. A client of a firm cannot create one.
Create an API key
Section titled “Create an API key”Create keys in the SuperDocs portal, in your settings. Your firm’s API access must be switched on first. Getting started has the steps.
- Create one key for each program. Then you can revoke one program’s key without stopping the others.
- You can hold at most 10 live keys. A live key is one that is not revoked and not expired.
When you create a key, you give it a name, for example “Billing export”. The name helps you tell your keys apart.
The key is shown only once
Section titled “The key is shown only once”SuperDocs shows the key once, when you create it. SuperDocs does not store the key itself, so nobody can show it to you again, not even SuperDocs support.
If you lose a key, revoke it and create a new one.
How long does a key last?
Section titled “How long does a key last?”When you create a key, you choose how long it lasts:
| Choice | The key stops working |
|---|---|
| One year (the default) | one year after you create it |
| 90 days | 90 days after you create it |
| 30 days | 30 days after you create it |
| No expiry | only when you revoke it |
An expired key gets the same 401 answer as any other key the API does not accept. Create a new key before the old one expires, change your program to use it, and then revoke the old key.
Revoke an API key
Section titled “Revoke an API key”Revoke a key in the SuperDocs portal, on the same screen where you created it. Revoke a key when:
- you no longer need it,
- you think someone else has seen it,
- a person who knew the key leaves your team.
A revoked key stops working at the next request. A firm admin can also revoke the keys of other users in the firm.
When does a key stop working by itself?
Section titled “When does a key stop working by itself?”A key stops working when:
- it expires,
- it is revoked,
- its user leaves the firm,
- its user becomes a client of the firm instead of a firm user.
A password change does not end your API keys. If you change your password because you think someone knows it, also revoke your keys in the portal.
If your firm’s API access is switched off, every request answers 403 until it is switched on again.
Test and live keys are separate
Section titled “Test and live keys are separate”A key works in one SuperDocs environment only. A key from a test environment does not work in the live environment, and a live key does not work in a test environment. Create a separate key in each environment.
What do 401 and 403 mean?
Section titled “What do 401 and 403 mean?”| Status | What it means |
|---|---|
401 |
The API did not accept the key. The key is missing, malformed, unknown, revoked or expired, or its user is no longer in the firm. The answer is the same in every case, so the API does not tell you which one it is. |
403 |
The key is good, but your firm’s API access is switched off. |
When you get a 401, check that you sent the whole key. If you did, create a new key.
Errors lists every error.
Keep your API key safe
Section titled “Keep your API key safe”An API key gives the same read access as signing in as you. Treat it like a password.
- Keep it on a server. Use the key only in a program that runs on a computer you control.
- Never put it in a web page or in browser code. Anyone who opens the page can read it.
- Never put it in a mobile app. Anyone can take an app apart and read the key.
- Never put it in source control, such as a Git repository. Read it from an environment variable or a secret store instead.
- Never send it by email or chat, and never paste it into a support request.
- Give each program its own key, and revoke the keys you no longer use.
If you think someone else has seen your key, revoke it at once and create a new one.