# Anmeldung und Berechtigungen

## Schlüssel

Jede Anfrage trägt den API-Schlüssel Ihres Unternehmens:

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

- **Erstellt** unter **[Einstellungen › API](/settings/api)** vom Inhaber oder der Buchhaltung und nur einmal angezeigt. Ocost speichert bloß einen Fingerabdruck: Einen verlorenen Schlüssel widerrufen und ersetzen Sie.
- **Der Anfang,** `ocost_sk_<id>_`, ist nicht geheim. Die Einstellungen listen Schlüssel danach, mit Berechtigungen und letzter Nutzung; am Präfix `ocost_sk_` erkennen Secret-Scanner ein Leck.
- **Ein Unternehmen je Schlüssel,** und nie Personalunterlagen (Lohnabrechnungen, Gehaltslisten, Gesundheit). Eine Odoo-Firma ist ein Unternehmen mit eigenem Schlüssel.
- **Widerrufen** gilt ab der nächsten Anfrage. Ein Schlüssel kann auch an einem Datum ablaufen.
- **Höchstens 10 gültige Schlüssel** je Unternehmen. Zum Wechseln einen neuen erstellen, umstellen, den alten widerrufen.
- **Nur auf dem Server:** nie in einem Browser, einer App oder einem Log.

## Berechtigungen

Einstellungen › API hakt alle drei vor.

| Berechtigung | Routen |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}` |
| `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}` |
| `search:read` | `GET /public/v1/search` |

## Ablehnungen

| Antwort | Wann |
| --- | --- |
| `401 urn:ocost:key:invalid` | Kein Schlüssel oder ein ungültiger, falscher, widerrufener, abgelaufener oder der eines gelöschten Unternehmens. Immer dieselbe Antwort. |
| `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` | Ein `Ocost-View…`-Header, den nur Ocosts Web-App schickt. |

## Beispiel

```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());
```