Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

API keys

This page explains how to create, use, revoke and protect your API keys.

Send the key with every request, as a bearer token in the Authorization header:

Terminal window
curl \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/ping

The 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.

An API key looks like this example:

sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY

A 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.

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 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.

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.

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 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.

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.

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.

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.

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.