# Schlüssel und Berechtigungen

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 › API](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 einem Unternehmen. Eine Odoo-Firma ist ein Unternehmen mit eigenem Schlüssel. Ein Unternehmen hat höchstens 10 gültige Schlüssel. Ein Schlüssel kann auch an einem Datum ablaufen.

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

## 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 › API 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}`, 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://docs.ocost.io/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. |
| `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. |