# APIs

APIs als OAuth-Ressourcen schützen: Scopes definieren, Machine-to-Machine- und Benutzerzugriff steuern, Token-Format und -Lebensdauern festlegen.

Eine **API** stellt eine geschützte Ressource dar, für die Anwendungen Access Token beziehen. Das Registrieren einer API teilt der Plattform die Kennung der Ressource (ihre Audience), die von ihr bereitgestellten **Scopes** (Berechtigungen), welche Anwendungen sie aufrufen dürfen und wie die von ihr ausgestellten Access Token geformt und signiert werden.

Sie verwalten APIs in der Admin Console unter **Integrations → APIs**.

## Was eine API ist

Jede API hat:

- einen **Namen**: eine Beschriftung für Administratoren, und
- eine **Kennung**: den Audience-Wert, der in Token erscheint, die für diese API ausgestellt werden (zum Beispiel `https://api.example.com`).

Bei einer eigenen API können Sie außerdem **Kontakte** hinterlegen, also die Mitarbeiter, die dazu Ansprechpartner sind. Sie sind rein informativ und erhalten keine Rechte.

Es gibt zwei Arten:

- **System API**: die eigene Management-API der Plattform. Ihr Name, ihre Kennung und ihre Scopes sind fest und können nicht bearbeitet werden.
- **Custom API**: eine API, die Sie registrieren und steuern: Sie definieren ihre Scopes, wer sie aufrufen darf, und ihre Token-Einstellungen.

## Scopes (Berechtigungen)

Ein Scope ist eine einzelne Berechtigung, die ein Token tragen kann, zum Beispiel `read:documents` oder `orders.write`.

- Die **System API** stellt einen festen Katalog an Management-Scopes bereit (zum Beispiel `users.read`, `users.write`, `groups.read`, `roles.write`, `logs.read`). Das sind die Scopes, die Sie Anwendungen gewähren, die die eigene Management-API der Plattform aufrufen.
- Eine **Custom API** stellt die Scopes bereit, die *Sie* definieren. Fügen Sie auf der Registerkarte permissions der API jeden Scope mit einem Namen und einer Beschreibung hinzu. Einige reservierte OpenID Connect-Scopes (wie `openid`, `profile`, `email`, `offline_access`) können nicht neu definiert werden.

Einige Management-Scopes stehen bewusst neben ihrem Basis-Scope, anstatt von ihm eingeschlossen zu werden. Zu kennen ist vor allem `users.mfa.read`: Der Scope deckt die MFA-Registrierungen eines Benutzers ab (welche zweiten Faktoren registriert sind und wann jeder zuletzt verwendet wurde). Er ist an **jedem** Endpunkt erforderlich, der einen Benutzer zurückgibt, also auch in den Antworten von Anlegen, Aktualisieren, Löschen sowie den Aufrufen zum Deaktivieren und Aktivieren. Ein Token, das nur `users.read` oder `users.write` trägt, erhält den Benutzer ohne die Liste der Registrierungen. Gewähren Sie `users.mfa.read` daher zusätzlich, wenn eine Integration sie benötigt.

## Wer eine API aufrufen darf

Zwei unabhängige Richtlinien steuern den Zugriff, eine für jede Art von Aufrufer:

### Benutzerdelegierter Zugriff [#user-delegated-access]

Wenn eine interaktive Anwendung einen Token *im Namen eines angemeldeten Benutzers* anfordert, entscheidet die **user policy** der API, ob dies erlaubt ist:

- **Allow all**: jede interaktive Anwendung darf Token für diese API anfordern.
- **Require grant**: nur Anwendungen, die Sie ausdrücklich gewährt haben, dürfen Token anfordern, und nur für die Scopes, die Sie ihnen gewähren.
- **Deny all**: keine interaktive Anwendung darf Token anfordern.

### Machine-to-Machine-Zugriff

Wenn sich eine Anwendung *als sie selbst* mit dem Client-Credentials-Grant authentifiziert (kein Benutzer beteiligt), entscheidet die **client policy** der API, ob dies erlaubt ist:

- **Require grant**: nur Anwendungen, die Sie ausdrücklich gewährt haben, dürfen Token anfordern, begrenzt auf die gewährten Scopes.
- **Deny all**: keine Machine-to-Machine-Anwendung darf Token anfordern.

### Eine Anwendung gewähren [#granting-an-application]

Wo eine Richtlinie auf **require grant** steht, autorisieren Sie eine Anwendung auf der Registerkarte **application access** der API:

1. Wählen Sie **Add application** im Abschnitt benutzerdelegiert oder Client (Machine-to-Machine).
2. Wählen Sie die Anwendung aus.
3. Wählen Sie die zu gewährenden Scopes, oder wählen Sie **grant all permissions**, um aktuelle und zukünftige Scopes automatisch einzuschließen.
4. Speichern Sie. Token, die die Plattform dieser Anwendung für diese API ausstellt, tragen nun die gewährten Scopes.

Eine Machine-to-Machine-Anwendung ist typischerweise vom Anwendungstyp *machine-to-machine*, siehe [Anwendungen](https://dts-identity.com/de/docs/integrations/applications.md).

[Image: Die API-Liste in der Admin-Konsole]

## Einen API-Token testen

Sobald für eine API mindestens eine Machine-to-Machine-Anwendung autorisiert ist (mit dem Client-Credentials-Grant), können Sie auf der Registerkarte **Test** der API einen Token durchgängig ausprobieren, ohne Code zu schreiben:

1. Wählen Sie eine der autorisierten Machine-to-Machine-Anwendungen.
2. Die Seite zeigt einen ausführbereiten Beispiel-**Token-Request** gegen den Token-Endpunkt, der die Client ID und das Secret dieser Anwendung sowie die Kennung dieser API als Audience verwendet.
3. Sie zeigt die **Token-Response** und decodiert den ausgestellten Access Token in seinen **Header**, seine **Payload** und seine **Signatur**, damit Sie bestätigen können, dass Audience und gewährte Scopes Ihren Erwartungen entsprechen.
4. Sie zeigt einen Beispiel-**API-Aufruf**, der den Token als `Bearer`-Header sendet.

Kopieren Sie die Befehle, um sie in Ihrem eigenen Terminal auszuführen. Weist die Registerkarte Test Sie an, zuerst eine Anwendung zu autorisieren, gewähren Sie eine Machine-to-Machine-Anwendung auf der Registerkarte **application access** und laden Sie neu.

## Resource Indicators und Token [#resource-indicators-and-tokens]

Jeder Access Token, den die Plattform für eine API ausstellt, trägt die Kennung dieser API als seine **Audience**, sodass die Ressource verifizieren kann, dass der Token für sie bestimmt war. Anwendungen wählen über den Resource Indicator, für welche API sie einen Token wollen, wodurch eine Anwendung separate, audience-bezogene Token für mehrere APIs halten kann.

Auf der Registerkarte settings der API steuern Sie, wie diese Token geformt werden:

- **Signing algorithm**: der asymmetrische Algorithmus (RS256, RS384, RS512 oder PS256), mit dem die Token signiert werden. Wählen Sie **PS256** für eine API, die von einer Anwendung mit einem [Financial-grade-API-Sicherheitsprofil](https://dts-identity.com/de/docs/integrations/applications.md#financial-grade-api-security) aufgerufen wird: dieses Profil signiert die eigenen Token der Anwendung mit PS256 und rät von RS256 ab. Diese Einstellung ist unabhängig vom Profil und muss daher hier ebenfalls umgestellt werden.
- **Access token lifetime**: wie lange ein Token gültig ist (Standard ist ein Tag).
- **Implicit access token lifetime**: eine kürzere Lebensdauer für Token, die über browserbasierte Implicit-Flows ausgestellt werden (Standard sind zwei Stunden).

## Eine API oder mehrere? [#one-api-or-many]

Ein Access Token trägt immer genau **eine Audience**. Multi-Audience-Token werden nicht ausgestellt: Ein Token, der für eine API geprägt wurde, wird von einer anderen nicht akzeptiert (siehe [Die API als verifizierbarer Vertrag](#the-api-as-a-verifiable-contract)). Besteht Ihr Backend aus mehreren Microservices, ergibt sich daraus eine Designentscheidung:

**Eine logische API für eine Trust-Domain.** Registrieren Sie eine einzelne API, deren Kennung für das gesamte Backend steht (zum Beispiel `https://api.example.com`), und geben Sie jedem Service einen eigenen Scope-Namensraum (`orders.read`, `inventory.write` und so weiter). Jeder Service validiert dieselbe Audience und setzt nur seine eigenen Scopes durch; der Client hält einen Token für das gesamte Backend, und ein neuer Service kommt durch zusätzliche Scopes hinzu statt durch eine neue Registrierung. Wählen Sie dies, wenn die Services gemeinsam entwickelt und betrieben werden, typischerweise hinter einem Gateway. Beachten Sie den Kompromiss: Innerhalb der gemeinsamen Audience isolieren sich die Services nicht mehr über die Audience-Prüfung voneinander (jeder von ihnen akzeptiert einen Token, der an einen Schwester-Service geschickt wurde), sondern nur über die Scopes.

**Eine API pro Vertrauensgrenze.** Registrieren Sie getrennte APIs, wenn die Ressourcen unterschiedliche Vertrauensstufen oder Eigentümer haben oder Dritte beteiligt sind. Ein Client fordert dann über den Resource Indicator einen separaten Token pro API an (siehe [Resource Indicators und Token](#resource-indicators-and-tokens)), und ein Backend-Dienst kann einen bereits gehaltenen Token per [Token Exchange](#token-exchange) tauschen. Über die Grenze hinweg bleibt die Audience-Prüfung aussagekräftig: Ein bei einer API abgegriffener Token ist bei der anderen wertlos.

Eine Mischung aus beidem ist üblich: eine logische API für den zusammenhängenden Kern, getrennte APIs für die Teile, die stärkere Isolation benötigen.

**Wie weit der Token eines Benutzers weitergereicht werden sollte.** Behandeln Sie den Access Token des Benutzers als Credential, nicht als Request-Kontext. Reichen Sie ihn höchstens einen Hop weit weiter, vom Client bis an Ihre API-Kante (das Gateway oder den ersten Service). Services tiefer in einer Aufrufkette sollten entweder hinter der gemeinsamen Audience der logischen API liegen oder einen schmaleren, per Token Exchange geprägten Token erhalten; jeder zusätzliche Hop, den der ursprüngliche Token zurücklegt, vergrößert die Fläche, auf der ein geleakter Token wiederverwendet werden kann.

## Token Exchange [#token-exchange]

Der Token-Endpunkt unterstützt **OAuth 2.0 Token Exchange** (RFC 8693), damit ein Service eine nachgelagerte API im Namen eines angemeldeten Benutzers aufrufen kann, ohne den ursprünglichen Token weiterzureichen: Die Anwendung tauscht einen bereits gehaltenen Benutzer-Access-Token gegen einen neuen, schmaleren Token für eine andere API.

Der Grant ist bewusst auf **Downscoping** begrenzt:

- Nur eine **web**-Anwendung (confidential) kann ihn verwenden, und nur wenn **Token exchange** unter ihren Grant-Typen aktiviert ist (siehe [Anwendungen](https://dts-identity.com/de/docs/integrations/applications.md)).
- Der Subject Token muss ein noch gültiger **Benutzer-Access-Token sein, der derselben Anwendung ausgestellt wurde**, die den Tausch durchführt. Das Tauschen von Token anderer Anwendungen, von Token ohne Benutzer oder Delegation mit einem `actor_token` wird nicht unterstützt.
- Die Anfrage benennt über `resource` **genau eine Ziel-API**. Die [Richtlinie für benutzerdelegierten Zugriff](#user-delegated-access) der Ziel-API gilt für die tauschende Anwendung wie bei jedem anderen Token-Request.
- Der ausgestellte Token ist **nie breiter als der Subject Token**: Seine Scopes sind die Schnittmenge aus den angeforderten Scopes, den Scopes des Subject Token, den Scopes der Ziel-API und dem, worauf der Benutzer Anspruch hat.
- Der neue Token bleibt an denselben Benutzer und dieselbe Session gebunden und folgt den Token-Lebensdauer-Einstellungen der Ziel-API.

Beispiel-Request gegen den Token-Endpunkt (die Anwendung authentifiziert sich wie üblich, zum Beispiel mit ihrem Client Secret):

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.read
```

Die Antwort enthält den neuen `access_token` zusammen mit `expires_in` und dem tatsächlich gewährten `scope`.

## Scopes vs. Berechtigungen [#scopes-vs-permissions]

Einen Scope auf einer API zu definieren macht ihn nur *anforderbar*; es gewährt niemandem Zugriff darauf. Was tatsächlich in einem Token landet, wird separat entschieden:

- **Bei Machine-to-Machine-Token** trägt der Token genau die Scopes, die der Client-Grant der Anwendung autorisiert (siehe [Eine Anwendung gewähren](#granting-an-application)). Ein Maschinen-Client hat keinen Benutzer und keine Rollen, sodass **das Zuweisen einer Rolle an eine Machine-to-Machine-Anwendung keine Wirkung hat**; seine Scopes stammen allein aus dem Grant.
- **Bei benutzergebundenen Token** (ausgestellt, wenn eine interaktive App einen Token im Namen eines angemeldeten Benutzers anfordert) entscheidet die [rollenbasierte Zugriffskontrolle](#role-based-access-control), auf welche Scopes der Benutzer Anspruch hat. Die Scopes, die letztlich im Token landen, sind die **Schnittmenge** aus dem, was die Anwendung angefordert hat, und dem, worauf der Benutzer Anspruch hat.

Das ist die übliche Antwort auf *„Warum fehlt der von mir angeforderte Scope stillschweigend in meinem Token?"*: Der Scope wurde angefordert, aber der Aufrufer hatte keinen Anspruch darauf, sodass er verworfen statt abgelehnt wurde.

> **Defense in Depth:** Ein in einem Token vorhandener Scope ist eine *Gewährung*, keine Garantie. Ihre API sollte weiterhin ihre eigenen Prüfungen auf Objektebene durchsetzen (besitzt *dieser* Benutzer *diesen* Datensatz?); ein gültiger Token mit einem breiten Scope ersetzt nicht die Autorisierung an der Ressource selbst.

## Rollenbasierte Zugriffskontrolle [#role-based-access-control]

> **Plan-Hinweis:** Die rollenbasierte Zugriffskontrolle ist ab dem Advanced-Tarif verfügbar (sowie in Trial).

Eine Custom API kann sich für RBAC entscheiden, wodurch die Plattform die Rollen und Berechtigungen eines Benutzers direkt in die Token einbetten kann, die sie für diese API ausstellt. Auf der Registerkarte settings der API:

- **Rollen und Berechtigungen aufnehmen (RBAC)** schaltet es für die API ein.
- **permissions-Claim aufnehmen** schließt die gewährten Scopes des Benutzers für diese API als `permissions`-Claim ein.
- **roles-Claim aufnehmen** schließt die Rollennamen des Benutzers als `roles`-Claim ein.

Diese Claims werden nur zu **benutzergebundenen** Token hinzugefügt. Die Anwendung trifft dann Autorisierungsentscheidungen anhand dieser Claims. Um Rollen zu definieren und Benutzern und Gruppen zuzuweisen, siehe [Rollen](https://dts-identity.com/de/docs/integrations/roles.md).

Diese Entscheidungen gehören in das **Access Token**. Ein Claim `roles` erreicht auch das ID Token, wenn eine Anwendung den Scope `roles` anfordert, dieser dient aber nur der Darstellung, siehe [Im Access Token durchsetzen, nicht im ID Token](https://dts-identity.com/de/docs/integrations/roles.md#enforce-on-the-access-token-not-the-id-token).

## Die API als verifizierbarer Vertrag [#the-api-as-a-verifiable-contract]

Eine registrierte API ist im Grunde ein Vertrag zwischen Ihnen und dem Resource Server:

- Ihre **Kennung** ist stabil und wird zur **Audience** jedes Tokens, der für sie ausgestellt wird.
- Die Plattform **signiert** jeden Token mit ihrem Signaturschlüssel (siehe [Signaturschlüssel](https://dts-identity.com/de/docs/settings/signing-keys.md)).
- Der Resource Server validiert den Token, bevor er einem Scope vertraut: Er prüft die **Signatur**, dass der **Issuer** diese Plattform ist und dass die **Audience** mit seiner eigenen Kennung übereinstimmt, und liest dann die Scopes.

Schlägt eines davon fehl, sollte der Resource Server die Anfrage rundweg ablehnen.

## Die Management-API aufrufen (Machine-to-Machine-Quickstart) [#call-the-management-api-machine-to-machine-quickstart]

Damit ein Skript oder Backend-Dienst die eigene Management-API der Plattform aufrufen kann:

1. Erstellen Sie eine **machine-to-machine**-Anwendung, siehe [Anwendungen](https://dts-identity.com/de/docs/integrations/applications.md).
2. Gewähren Sie dieser Anwendung auf der application-access-Registerkarte der **System API** die Management-Scopes, die sie benötigt (zum Beispiel `users.read`, `groups.write`). Gewähren Sie nur die Scopes, die die Integration tatsächlich verwendet.
3. Fordern Sie von Ihrem Dienst aus einen Token mit dem **client-credentials**-Grant gegen den Token-Endpunkt an, wobei Sie die Kennung der System API als **Audience** verwenden.
4. Rufen Sie die Management-Endpunkte unter `/api/v1/...` mit dem zurückgegebenen Token im `Authorization: Bearer`-Header auf.

Die Registerkarte **Test** der System API generiert genau diese beiden Befehle für Sie, vorbefüllt mit einer echten Anwendung; kopieren Sie sie als Ausgangspunkt.

Ein Token wird schon vor seinem Ablauf ungültig, sobald die Anwendung ihren Zugriff auf die System API verliert, ihr Client-Secret rotiert oder die Anwendung gelöscht wird. Der Dienst erhält dann `HTTP 401` und muss einen neuen Token anfordern.

## Machine-to-Machine-Token-Limits [#machine-to-machine-token-limits]

Für Tokens aus dem client-credentials-Grant gelten zwei Limits. Beide werden in der Übersicht unter **Integrationen → APIs** angezeigt. Tokens für interaktive Benutzeranmeldungen sind von keinem der beiden betroffen.

**Token-Anfragen pro Minute und Client**: das Durchsatzlimit. Anfragen darüber hinaus werden mit `HTTP 429` und einem `Retry-After`-Header beantwortet; der Client kann es nach der dort genannten Wartezeit erneut versuchen.

| Plan | Token-Anfragen pro Minute |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1.200 |
| Advanced | 6.000 |
| Pro | 30.000 |

**Tokens pro Monat, mandantenweit**: ein Volumenbudget, das nur in den Einstiegsplänen existiert. Es umfasst alle Machine-to-Machine-Anwendungen und alle APIs zusammen und wird am 1. jedes Monats zurückgesetzt. Ist es verbraucht, werden weitere client-credentials-Anfragen mit `access_denied` beantwortet, bis der nächste Monat beginnt.

| Plan | Tokens pro Monat |
|---|---|
| Trial / Free | 1.000 |
| Essential und höher | Unbegrenzt |

Ein Client, der seinen Access-Token über die volle Token-Lebensdauer zwischenspeichert, benötigt etwa 720 Tokens pro Monat und bleibt damit weit unter beiden Limits. Erreicht wird eines davon im Normalfall nur von einem Client, der für jeden einzelnen API-Aufruf einen neuen Token anfordert. Speichern Sie den Token im aufrufenden Dienst zwischen und verwenden Sie ihn bis kurz vor Ablauf weiter; die Token-Lebensdauer wird pro API auf der Einstellungs-Registerkarte der API konfiguriert.

## Entwickler- / API-Referenz

Die Plattform liefert interaktive, produktintegrierte API-Dokumentation unter **/admin/api-docs**. Sie listet jeden Management-Endpunkt mit seinen Parametern auf und lässt Sie Aufrufe im Browser ausprobieren, und Sie können die maschinenlesbare OpenAPI-Definition von derselben Seite herunterladen.

Die Management-API deckt die Administration von Benutzern, Gruppen, Organisationen, Anwendungen, Rollen, Logs und Geräten ab. Verwenden Sie **/admin/api-docs** als maßgebliche Endpunktreferenz statt einer statischen Liste hier.

## Referenz

| Begriff | Bedeutung |
|---|---|
| Kennung (Audience) | Der Wert, der die API identifiziert; erscheint in Token, die für sie ausgestellt werden. |
| Scope / Berechtigung | Eine einzelne Fähigkeit, die ein Token tragen kann. |
| User policy | Ob interaktive Anwendungen Token im Namen eines Benutzers beziehen dürfen. |
| Client policy | Ob Anwendungen Token für sich selbst beziehen dürfen (Machine-to-Machine). |
| Grant | Eine ausdrückliche Autorisierung einer Anwendung, diese API mit bestimmten Scopes aufzurufen. |
| RBAC | Das Einbetten der Rollen und Berechtigungen eines Benutzers in die Token der API. |
| Token Exchange | Der Tausch eines Benutzer-Access-Tokens gegen einen schmaleren Token für eine andere API (RFC 8693). |

## Fehlerbehebung

- **Der Token-Request wird mit einem ungültigen Scope abgelehnt.** Eine Anwendung kann nur Scopes anfordern, die ihr auf der API gewährt wurden. Fügen Sie den Scope zum Grant der Anwendung für diese API hinzu und fordern Sie dann einen frischen Token an.
- **Aufrufe geben einen Insufficient-Scope-Fehler zurück, obwohl ein Token ausgestellt wurde.** Eine Anfrage gelingt nur, wenn der Token tatsächlich den Scope trägt, den der Endpunkt erfordert. Decodieren Sie den Token und bestätigen Sie, dass die gewährten Scopes ihn enthalten; Scopes, die der Anwendung nicht gewährt wurden, werden stillschweigend aus dem Token verworfen.
- **Der Token hat die falsche Audience.** Der Token muss für die Kennung (Audience) dieser API angefordert werden. Ein Token, der für eine andere API oder ohne Audience geprägt wurde, wird hier nicht akzeptiert.
- **Der Token-Test gibt nichts oder einen Fehler zurück.** Der Test stellt einen Token für die ausgewählte Anwendung und die ausgewählten Scopes aus. Stellen Sie sicher, dass die Anwendung einen aktiven Grant auf dieser API hat und dass mindestens ein Scope ausgewählt ist.
- **Ein Token Exchange wird abgelehnt.** Der Subject Token muss ein noch gültiger, benutzergebundener Access Token sein, der derselben Anwendung ausgestellt wurde, die den Tausch durchführt; die Anwendung muss den Token-Exchange-Grant aktiviert haben, und die Anfrage muss über `resource` genau eine Ziel-API benennen. Machine-to-Machine-Token (ohne Benutzer) können nicht getauscht werden.

Siehe auch das [Glossar](https://dts-identity.com/de/docs/reference/glossary.md).
