Skip to main content

​
API keys

Every GET request to an endpoint needs an API key. A key belongs to one workspace and reads only the data of that workspace. A key is read-only. A key belongs to the workspace, not to the person who created it. It keeps working if that person leaves the team or gets another role. If you remove a member who created keys, revoke those keys yourself. 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. Members and viewers do not see the key list. They see the notice Nur Lesen. instead.
1

Open the key settings

Open Einstellungen, then the Integrationen tab. The card API-Keys lists your keys.
2

Create the key

Select API-Key erstellen. Enter a Name, up to 80 characters. Optionally set Gültig bis (optional). Without a date the key is valid until you revoke it. Select Erstellen.
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 API-Key erstellen is disabled.
  • A workspace can create at most 20 new keys in 24 hours.

​
Key status and last use

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

​
Send the key

Send the key in the Authorization header with the Bearer scheme:
Do not send the key in the query string, in a cookie or in a body. The API does not read it from there. An Authorization header longer than 256 characters is not evaluated and returns 401.

​
Missing or invalid key

The API returns 401 with the same body in all of these cases:
  • The Authorization header 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.
The response carries the header WWW-Authenticate: Bearer. It gives no hint whether a key exists. See Errors for the order of checks.

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