# Schlüssel und Berechtigungen
> API-Schlüssel: wie eine Anfrage einen trägt, ihr Wechsel, ihre Berechtigungen und die Ablehnungen.

Jede Anfrage trägt den API-Schlüssel Ihres Unternehmens im Header `Authorization`:

```text
Authorization: Bearer ocost_sk_<id>_<secret>
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
```

## Schlüssel

Inhaber oder Buchhaltung erstellen Schlüssel unter [Einstellungen › Entwickler](https://app.ocost.io/settings/api). Ocost zeigt einen Schlüssel einmal und speichert nur einen Fingerabdruck. Verlieren Sie einen Schlüssel, widerrufen Sie ihn und erstellen Sie einen neuen.

Der Anfang eines Schlüssels, `ocost_sk_<id>_`, ist nicht geheim. Die Einstellungen listen Schlüssel danach, mit Berechtigungen und letzter Nutzung. Secret-Scanner erkennen am Präfix `ocost_sk_` ein Leck.

Ein Schlüssel gehört zu dem Unternehmen, in dem er erstellt wurde. Ein Unternehmen hat höchstens 10 gültige Schlüssel. Ein Schlüssel kann auch an einem Datum ablaufen.

> [!WARNING]
> Halten Sie Schlüssel auf Ihrem Server. Legen Sie nie einen in einen Browser, eine mobile App oder ein Log.

## Gesellschaften einer Gruppe

Der Inhaber einer Gruppe von Gesellschaften kann einem Schlüssel unter Einstellungen › Entwickler weitere davon geben. Ein Schlüssel erreicht dann alle, auch später hinzugekommene, oder eine Auswahl. Auch der Ocost-Support kann sie festlegen. Jede Änderung steht unter Einstellungen als Besuch von Ocost.

`GET /public/v1/businesses` listet die Gesellschaften, die ein Schlüssel erreicht, seine eigene zuerst. Jeder Schlüssel darf das fragen.

Nennen Sie die Gesellschaft einer Anfrage mit dem Header `Ocost-Business`, ihrer ID. Ohne ihn handelt die Anfrage im eigenen Unternehmen des Schlüssels.

```text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"
```

```python
files = session.get(
    "https://api.ocost.io/public/v1/files",
    headers={"Ocost-Business": company_id},
    timeout=15,
).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());
```

Schlüssel und Geheimnis bleiben gleich, wenn sich seine Gesellschaften ändern. Eine Gesellschaft, die er nicht mehr erreicht, lehnt Ocost ab der nächsten Anfrage ab. Ebenso eine, die die Gruppe verlässt.

[Unternehmensgruppen](https://ocost.io/docs/de/groups.md) erklärt, wie ein Schlüssel mehrere Gesellschaften erreicht und wo seine Dateien landen.

## Einen Schlüssel wechseln

1. Erstellen Sie einen neuen Schlüssel mit denselben Berechtigungen.
2. Stellen Sie Ihre Software auf ihn um.
3. Widerrufen Sie den alten Schlüssel. Ocost lehnt ihn ab der nächsten Anfrage ab.

## Berechtigungen

Ein Schlüssel darf nur, was seine Berechtigungen erlauben. Einstellungen › Entwickler hakt für einen neuen Schlüssel die ersten drei vor.

| Berechtigung | Erlaubt |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`, `PATCH /public/v1/files/{file_id}`, das MCP-Werkzeug `send_file` |
| `documents:read` | `GET /public/v1/files`, `GET /public/v1/files/{file_id}`, `GET /public/v1/files/{file_id}/content`, `GET /public/v1/files/{file_id}/document`, `GET /public/v1/documents/{document_id}` und die MCP-Werkzeuge, die Datensätze lesen |
| `search:read` | `GET /public/v1/search` und die Suchwerkzeuge des MCP |
| `figures:read` | Die Zahlenwerkzeuge des MCP. Nur der Inhaber erstellt einen Schlüssel damit. |
| `exports:write` | Die Exportwerkzeuge des MCP |

[MCP-Werkzeuge](https://ocost.io/docs/de/tools.md) listet jedes Werkzeug unter seiner Berechtigung.

Kein Schlüssel liest je Personalunterlagen wie Lohnabrechnungen, Gehaltslisten oder Gesundheitsunterlagen.

## Ablehnungen

| Antwort | Wann |
| --- | --- |
| `401 urn:ocost:key:invalid` | Kein Schlüssel, oder ein ungültiger, falscher, widerrufener oder abgelaufener, oder der eines gelöschten Unternehmens. Die Antwort ist immer dieselbe. |
| `403 urn:ocost:key:scope` | Dem Schlüssel fehlt die Berechtigung der Route. |
| `403 urn:ocost:key:business` | Der Schlüssel erreicht die Gesellschaft nicht, die `Ocost-Business` nennt. |
| `400 urn:ocost:key:business` | `Ocost-Business` ist keine ID einer Gesellschaft. |
| `429 urn:ocost:key:rate` | Zu viele Anfragen, oder zu viele falsche Schlüssel von einer Adresse. Warten Sie `Retry-After` Sekunden. |
| `400` | Die Anfrage hat einen Header `Ocost-View…`, den nur Ocosts Web-App schickt. |

## Siehe auch

- [Unternehmensgruppen](https://ocost.io/docs/de/groups.md): Unternehmensgruppen: welche Gesellschaften ein Schlüssel erreicht, der Header Ocost-Business, das Umleiten nach den Kennungen des Belegs, needs_company und Dateien in der Gruppe.
- [Grenzen und Fehler](https://ocost.io/docs/de/limits.md): Die Belege des Tarifs im Monat, Ratenlimits, Größen, Fehler nach RFC 9457, Wiederholen und wo die Daten liegen.
- [Einen Assistenten verbinden](https://ocost.io/docs/de/mcp.md): Einen Assistenten mit dem MCP-Server verbinden (https://api.ocost.io/public/mcp, dieselben Schlüssel): Claude Code, Claude Desktop, Cursor, claude.ai und ChatGPT über OAuth und jeder Client.
- Auf ocost.io: [API und MCP](https://ocost.io/produkt/api-und-mcp)
