> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifizierung per API einrichten mit Didit

> Anmeldemethoden, Einstellungen, Branding und Schutz von Didit per Code aktivieren – mit genehmigtem Grant oder API-Schlüssel für Authentifizierung.

Didit Authentication ermöglicht es Ihnen, Anmeldemethoden per API zu aktivieren und die Einstellungen Ihrer Anwendung per API abzurufen. Verwenden Sie eine vom Inhaber genehmigte Berechtigung oder einen benannten API-Schlüssel mit dem Scope `authentication`.

> [!WARNING]
>
> Authentication ist neu. Richten Sie eine Methode zuerst in einer Sandbox-Anwendung ein und danach in Ihrer Live-Anwendung.

Alle folgenden Aufrufe gehen an die Authentication-Management-API Ihrer Anwendung. `MANAGEMENT_BASE` lautet:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

Dieselben Routen sind in `openapi-authentication.json` unter dem Tag `Setup` beschrieben, aus der die Server-SDKs neu generiert werden.

## Welche Zugangsdaten Sie verwenden sollten

Alle drei Zugangsmittel funktionieren, und jedes ist auf das beschränkt, was sein Inhaber genehmigt hat.

| Zugangsmittel | Übermittelt als | Was es tun kann |
| - | - | - |
| Benannter API-Schlüssel mit dem Scope `authentication` | `x-api-key: <key>` | Konfiguriert die eigene Anwendung und liest sie. Ein Schlüssel mit `read` kann die Konfiguration nur lesen; mit `write` kann er sie lesen und ändern. |
| Vom Inhaber genehmigte Freigabe mit `didit:management` | `Authorization: Bearer <access_token>` | Konfiguriert die Anwendungen der Organisationen, die bei der Einwilligung genehmigt wurden, im Rahmen der Rolle der Person. |
| Console-Sitzung | `Authorization: Bearer <console session token>` | Liest oder ändert Einstellungen entsprechend der Organisationszugehörigkeit und Rolle der Person. Ansichten für Endbenutzer erfordern ebenfalls eine Console-Sitzung und die passenden Berechtigungen. |

Diese Zugangsdaten werden auf jeder Konfigurationsroute mit `403` abgelehnt, unabhängig davon, was die Anfrage verlangt:

* Das **primäre Geheimnis** der Anwendung.
* Ein Token aus `POST /programmatic/login`. Es wird für die Anwendung ausgestellt, nicht für die Console.
* Ein Schlüssel **ohne** den Scope `authentication`. Dazu gehört auch ein Schlüssel, der mit allen Ressourcen auf der höchsten Stufe erstellt wurde. Solche Schlüssel werden als Vollzugriff aufgeführt, `scopes` bleibt leer, und sie werden auf diesen Routen nicht akzeptiert.
* Ein Schlüssel einer **anderen Anwendung**, eine Freigabe, die nur auf `didit:verification` beschränkt ist, und eine Freigabe, die für eine andere Organisation genehmigt wurde.

Eine Anfrage ganz ohne Zugangsdaten beantwortet die API mit `401`. Eine Freigabe oder ein Schlüssel behält zusätzlich die eigenen Grenzen: Die Freigabe gilt nur für ihre Scopes, Organisationen und die Rolle der Person, der Schlüssel nur für seine Scopes, seine IP-Allowlist und sein Ablaufdatum.

## Zugriff genehmigen

### Mit einem benannten API-Schlüssel

Öffnen Sie **Developers -> API keys** in der [Business Console](https://business.didit.me) und erstellen Sie einen Schlüssel für die Anwendung, die Sie einrichten. Weisen Sie ihm die Ressource `authentication` mit **Lesen** oder **Schreiben** zu: Lesen umfasst alle Aufrufe, die das Setup lesen (`GET`). Schreiben umfasst alle Aufrufe, die es ändern (`POST`, `PUT`, `PATCH`, `DELETE`), und auch alle Leseaufrufe. Informationen zu Ablauf, IP-Allowlists und Rotation finden Sie unter [API-Schlüssel](https://docs.didit.me/de/console/api-keys.md). Ein Schlüssel gehört zu genau einer Anwendung und funktioniert nur für diese.

### Über eine MCP-Verbindung

Ein Agent, der mit dem Didit-MCP-Server verbunden ist, verwendet die Berechtigung, die sein Eigentümer auf dem Zustimmungsbildschirm genehmigt hat, mit `didit:management`. Siehe [MCP-Authentifizierung](https://docs.didit.me/de/integration/mcp/authentication.md#mit-didit-anmelden).

### Für Eigentümer ohne Passwort

Der Device-Code-Grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) ermöglicht es einem Eigentümer, der sich mit Google, einem Passkey oder einem per E-Mail gesendeten Code anmeldet, denselben Zugriff von jedem Browser aus zu genehmigen, ohne ein Passwort einzugeben. Siehe [Anmeldung ohne Browser](https://docs.didit.me/de/integration/mcp/authentication.md#anmeldung-ohne-browser-device-code).

## E-Mail-Code aktivieren

`PUT methods/{name}/` akzeptiert `enabled` und sonst nichts für eine Methode, die keine Zugangsdaten benötigt.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

Die Antwort gibt die Methode in ihrem aktuellen Zustand zurück:

```json theme={null}
{"name": "code", "enabled": true}
```

Wenn Sie die Konfiguration auslesen, enthält der Eintrag für den E-Mail-Code `credential_source: null`. Methoden, die immer aktiv sind, lassen sich nicht deaktivieren: Diese Anfrage antwortet mit `{"enabled": "always_on"}`.

## Google aktivieren

Eine Social-Methode benötigt die Zugangsdaten Ihrer eigenen OAuth-App oder die Test-App von Didit für eine **Sandbox-Anwendung**.

### Mit Ihrer eigenen Google-App

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Registrieren Sie die `callback_uri` aus der Antwort bei Ihrem Anbieter. Das Geheimnis ist nur schreibbar: Es wird von keiner Antwort zurückgegeben, und nur `client_id` lässt sich wieder auslesen. Wenn Sie eine Methode ohne Zugangsdaten aktivieren, obwohl zuvor keine gespeichert waren, lautet die Antwort `{"credentials": "required"}`.

### Mit der Test-App von Didit (`didit_test`)

Eine **Sandbox-Anwendung** kann anstelle Ihrer eigenen Social-Apps die Social-Apps von Didit verwenden. Das reicht aus, um eine Einrichtung abzuschließen und ihre Funktion zu prüfen:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` deckt **Google, Microsoft, Apple und GitHub** ab, und zwar nur für Sandbox-Anwendungen.

| Antwort | Wann |
| - | - |
| `{"credential_source": "sandbox_only"}` | Die Anwendung ist eine Produktionsanwendung. Test-Apps bedienen niemals Anmeldungen in der Produktion. |
| `{"credential_source": "unavailable"}` | In der Bereitstellung gibt es für diesen Anbieter keine Test-App, daher bleibt die Methode deaktiviert. |
| `200` mit `configured: true` | Die Test-App unterstützt die Methode, und die gehostete Anmeldung bietet sie an. |

Ein `GET` auf die Konfiguration nennt in `didit_test_credentials` die Anbieter, die eine Test-App für diese Anwendung bereitstellen kann. Bei einer Produktionsanwendung ist der Wert für alle vier Anbieter `false`.

## Einrichtung auslesen

`GET` auf `MANAGEMENT_BASE` gibt die gesamte Einrichtung zurück: jede Methode mit `enabled` und `credential_source` sowie die Callback-URLs, die Sitzungsregeln und die Registrierungsrichtlinie.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Deaktivierte Methoden werden ebenfalls aufgeführt, sodass ein einziges `GET` zeigt, was aktiviert ist und was nicht. `enabled` auf oberster Ebene ist `false`, wenn die Authentifizierung für die Anwendung deaktiviert ist. Jede Änderung an der Einrichtung, die mit einer Verwaltungsberechtigung oder einem benannten API-Schlüssel vorgenommen wird, gibt dann `409` mit `{"detail": "product_disabled"}` zurück, und es wird nichts geschrieben. Kein Einrichtungsaufruf schaltet die Authentifizierung ein: Das muss eine Person für die Anwendung in der Business Console tun. Danach funktionieren Ihre Aufrufe.

## Die übrige Einrichtung

| Route unter `MANAGEMENT_BASE` | Methoden | Inhalt |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Agentenzugriff, Organisationen, die MFA-Richtlinie, die standardmäßige Mitgliederrolle, deaktivierte Webhook-Ereignisse |
| `onboarding/` | `GET`, `PATCH` | Welche Einrichtungsschritte abgeschlossen sind und ob sich Personen auf der gehosteten Seite oder über Ihre eigenen Bildschirme anmelden |
| `branding/` | `GET`, `PATCH` | Die Texte und rechtlichen Links der gehosteten Seiten (Logo und Farben stammen aus Customization) |
| `protection/` | `GET`, `PATCH` | Die Richtlinien des [Bot-Schutzes](https://docs.didit.me/de/authentication/bot-protection.md) |
| `verified/` | `GET`, `PATCH` | Die Verifizierungsstufe bei der Registrierung, Step-up-Regeln und Token-Claims |
| `emails/`, `emails/{key}/` | `GET` | Die Anmelde-E-Mails, die diese Anwendung versendet, und eine gerenderte Vorschau |
| `domain/` | `GET`, `PUT`, `DELETE` | Der gehostete Ursprung und die benutzerdefinierte Anmelde-Domain |
| `domain/verify/`, `domain/activate/` | `POST` | Prüft DNS und Zertifikat der Domain und macht sie anschließend zum kanonischen Ursprung |
| `native-apps/` | `GET`, `PUT` | Die iOS- und Android-Apps, die die Passkeys der Anwendung teilen |

Ein Grant oder ein Schlüssel erhält nur Zugriff auf die Einrichtung und deren Zähler, niemals auf Endbenutzerdaten. Für `users/`, `sessions/`, `sign-ins/`, `overview/`, Kundenorganisationen, Rollen, Importe, Agenten-Sitzungen und Test-E-Mails ist weiterhin eine Konsolensitzung erforderlich.

Die Einstellung `agent_humans_only` gilt für die gesamte Anwendung. Nur ein Organisationsinhaber oder Administrator kann sie ändern. Ein benannter Schlüssel erhält `403 owner_or_admin_required`. Wenn Sie die Einstellung aktivieren, ist außerdem ein registrierter Passkey erforderlich (`passkey_required`).

## Fehler

| Antwort | Bedeutung |
| - | - |
| `401` | Keine Anmeldedaten. |
| `403` | Anmeldedaten, mit denen diese Anwendung nicht konfiguriert werden kann, oder eines der eigenen Limits: `ip_not_allowed`, ein abgelaufener Schlüssel, ein Schlüssel mit Nur-Lese-Zugriff bei einer Route für Schreibvorgänge. |
| `409 {"detail": "product_disabled"}` | Die Authentifizierung ist für die Anwendung deaktiviert, daher wird eine Änderung der Einrichtung, die mit einer Berechtigung oder einem Schlüssel vorgenommen wird, abgelehnt. Eine Person aktiviert sie in der Konsole. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | Die angeforderte Ressource wurde nicht gefunden. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.