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

| 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 |
| Permission | **Read only** or **Read and write**, chosen when you create the key |

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

## Send the key

Send the key in the `Authorization` header with the `Bearer` scheme:

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

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](https://docs.hocdoc.com/en/api/errors.md) 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](https://docs.hocdoc.com/en/api/errors.md).

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


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