API keys
Every request to an endpoint needs an API key. A key belongs to one workspace and reaches only the data of that workspace. A key has a permission: it reads, or it reads and writes.
A key belongs to the workspace and is tied to the person who created it. HocDoc revokes a key automatically when that person is removed from the workspace or is no longer an owner or admin. Giving the person the role back does not restore the key: create a new one. The key list shows who created each key (Erstellt am with the date, then von with the name).
Create a key
Only owners and admins can create and revoke keys, and only they create keys that write. Members and viewers do not see the key list. They see the notice Nur Lesen. instead.1
Open the key settings
Open Settings, then the Integrations tab. The card API keys lists your keys.
2
Create the key
Select Create API key. Enter a Name, up to 80 characters. Choose the permission Read only or Read and write. Optionally set Valid until (optional). Without a date the key is valid until you revoke it. Select Create.
3
Copy the key
The dialog API-Key erstellt shows the key. Select Kopieren, store the key in a safe place, then select Fertig. The text in the dialog says: “Dieser Key wird nur jetzt angezeigt. Bewahre ihn sicher auf.” You cannot show the key again.
Expiry
- Expiry is optional.
- You choose a date. The key is valid until the end of that day in the time zone of the workspace.
- The earliest date is today. The end of the chosen day can be at most 10 years ahead.
- You cannot change the expiry or the name of a key later. Revoke the key and create a new one.
Limits on the number of keys
- A workspace can have at most 10 keys that are not revoked. Expired keys count until you revoke them. At the limit the button Create API key is disabled.
- A workspace can create at most 20 new keys in 24 hours.
Key status and last use
The list shows the permission of each key. Keys that existed before the permission was introduced keep reading. The list shows one of these states for each key: Aktiv, Abgelaufen or Widerrufen. The list also shows when a key was last used (Zuletzt genutzt am) or Noch nicht genutzt. The time is written when the API accepts the key for a request, at most once per minute per key. It can therefore be up to a minute behind.Revoke a key
In the card API keys, select Widerrufen next to the key. In the dialog API-Key widerrufen, confirm with Widerrufen. You cannot undo this. A revoked key and an expired key stop working immediately. The next request with such a key returns401.
Send the key
Send the key in theAuthorization header with the Bearer scheme:
Authorization header longer than 256 characters is not evaluated and returns 401.
Missing or invalid key
The API returns401 with the same body in all of these cases:
- The
Authorizationheader is missing. - The scheme is not
Bearer. - The header is longer than 256 characters.
- The key has the wrong form.
- The key is unknown, revoked or expired.
WWW-Authenticate: Bearer. It gives no hint whether a key exists. See Errors for the order of checks.
Permission and acting person
A key with Read only reads offers and timelines. On a write path (POST /offers, POST /offers/{id}/send, POST /offers/{id}/withdraw) it gets 403 with the code forbidden. You cannot change the permission of a key later. Revoke it and create a new one.
A key with Read and write acts as the person who created it. The offers it creates count as that person’s, and that person’s role, the approval rules of the workspace, locked sections and the plan apply as in the app. Because only owners and admins create such keys, they need no approval before sending. If the database still requires an approval for the person, the API does not send and returns 409 with approval_required. See Errors.
Two-factor authentication
The two-factor rules of the HocDoc app apply when someone creates or revokes a key in the app. They do not apply to requests that carry a key, also not to writing requests. A key is its own secret without a session and without a person, so there is no second factor to present.Handle keys safely
- A key gives read access to all offers of the workspace and their timelines. A key with write permission can also create, send and withdraw offers. Treat it like a password.
- Use a key on a server. Do not put it in a browser or in a repository. The API sets no CORS headers.
- Give a key only the permission the system needs. Use one key per system, and give it a name that tells you which system that is. Then you can revoke one system without touching the others.
- If a key might have leaked, revoke it and create a new one.