# Authentifizierung und Scopes (https://developer.bimetrics.de/authentifizierung)

Wie der API-Schlüssel gesendet wird, welche Berechtigungen er hat und wie lange er gilt.

## Schlüssel senden

Sende den Schlüssel in genau einem Header, ausschließlich über HTTPS:

```http
Authorization: Bearer bm_…
```

Alternativ akzeptiert die API denselben Schlüssel im Header `X-API-KEY`:

```http
X-API-KEY: bm_…
```

Abgelehnt werden mit `401`:

* beide Header zugleich oder ein Header mehrfach,
* der Schlüssel als URL-Parameter (`?token=…`) oder per Basic-Auth,
* ein Schlüssel mit angehängter Firmen-ID (`bm_…:<id>`).

Die Firma ergibt sich aus dem Schlüssel. Ein Schlüssel besteht aus `bm_` und 43 Zeichen aus dem URL-sicheren Base64-Alphabet, insgesamt 46 Zeichen. Antworten auf Aufrufe mit Schlüssel tragen `Cache-Control: no-store`.

## Berechtigungen (Scopes)

Jeder Schlüssel hat eine oder beide Berechtigungen. Welche Berechtigung ein Endpunkt braucht, steht in der [Referenz](/referenz) bei jedem Endpunkt.

| Berechtigung | In der App       | Erlaubt                                                                                                    |
| ------------ | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `read`       | Daten lesen      | alle lesenden Endpunkte: Belege, Belegdateien, Kontakte, Bankkonten, Umsätze, Sachkonten, Buchungen, Tarif |
| `upload`     | Belege hochladen | [Beleg hochladen](https://developer.bimetrics.de/referenz/belege/upload-document.md)                                                                                                        |

Fehlt die Berechtigung oder ist ein Endpunkt nicht für API-Schlüssel freigegeben, antwortet die API mit `403` und dem Code `APIKeyPermissionDenied`. Vergib nur die Berechtigungen, die die Anwendung braucht.

## Laufzeit und Anzahl

* Ein Schlüssel gilt 30, 90 oder 365 Tage ab dem Anlegen. Danach antwortet die API mit `401`. Eine automatische Verlängerung gibt es nicht.
* Eine Firma hat höchstens fünf aktive Schlüssel gleichzeitig.
* Zum Austauschen legst du einen neuen Schlüssel an, stellst die Anwendung um und widerrufst dann den alten.

## Bindung an Inhaber und Tarif

Ein Schlüssel gehört zum Inhaber, der ihn angelegt hat, und zur gewählten Firma. Jeder Aufruf prüft Schlüssel, Ablauf, Widerruf, Mitgliedschaft und Tarif neu.

* Endet die Mitgliedschaft des Erstellers oder verliert er die Inhaberrolle, werden seine Schlüssel dauerhaft widerrufen.
* Ohne gültigen bezahlten Tarif oder eine Freischaltung durch bimetrics antwortet die API mit `403` und dem Code `APIUnavailable`.
* Ein Passwortwechsel widerruft keine Schlüssel.

## Sicher aufbewahren

> **Nie im Frontend-Code:** Wer den Schlüssel kennt, hat bis zum Ablauf vollen Lesezugriff auf die Daten der Firma und kann, mit der Berechtigung `upload`, Belege hochladen. Baue ihn nie in Browser-, Mobil- oder Desktop-Apps ein, die an Dritte gehen.

* Lege den Schlüssel nur serverseitig ab, etwa in einer Umgebungsvariable oder einem Secret-Store.
* Schreibe ihn nicht in URLs, Logs, Tickets oder Quellcode.
* Nutze je Anwendung einen eigenen Schlüssel. So kannst du einen einzelnen Zugang widerrufen, ohne andere zu stören.

## Widerrufen

Widerrufe einen Schlüssel in der App unter **Einstellungen › API** mit **Widerrufen**. Ab dann antwortet die API auf neue Aufrufe mit `401`; bereits laufende Aufrufe werden nicht abgebrochen. Widerrufe einen Schlüssel sofort, wenn er in falsche Hände geraten sein könnte oder du einen Zugang nicht kennst.