> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create API keys in the app and send them in the Authorization header.

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

| Property | Value |
| - | - |
| Format | `hd_live_` followed by 64 lowercase hexadecimal characters (72 characters in total) |
| Prefix shown in the app | The first 20 characters: `hd_live_` and 12 more characters |
| Storage | HocDoc stores a hash of the key and its first 20 characters, never the key itself |
| Visibility | The full key is shown once, right after you create it |
| Access | 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.

<Steps>
  <Step title="Open the key settings">
    Open **Einstellungen**, then the **Integrationen** tab. The card **API-Keys** lists your keys.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.hocdoc.com/api/v1/workspace" \
    -H "Authorization: Bearer hd_live_..."
  ```

  ```text Header theme={null}
  Authorization: Bearer hd_live_...
  ```
</CodeGroup>

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.

```json theme={null}
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key." } }
```

The response carries the header `WWW-Authenticate: Bearer`. It gives no hint whether a key exists. See [Errors](/api/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.