> ## 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. # Session abrufen | Didit Authentication API > Didit GET /session/ prüft ein Access-Token gegen die laufende Sitzung; bei Widerruf, Timeout, Sperrung oder Refresh schlägt sie sofort fehl. > [!WARNING] > > Authentifizierung ist neu. Diese Endpoints werden vom Aussteller Ihrer Anwendung bereitgestellt, etwa `https://.auth.didit.me`, und akzeptieren niemals Ihren Didit-API-Schlüssel. Dies ist die sofortige Widerrufsprüfung. Sie erlaubt pro IP-Adresse 30 Anfragen pro Minute und 300 pro Stunde. Prüfen Sie Token daher bei jeder Anfrage offline und rufen Sie diesen Endpoint vor sensiblen Aktionen auf. Siehe [Sitzung prüfen](https://docs.didit.me/de/authentication/tokens-and-jwks.md#sitzung-prüfen). ## OpenAPI ````yaml de/openapi-authentication.json GET /session/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- Die serverseitigen Endpoints von Didit Authentication, dem Anmeldeprodukt für die Endbenutzer Ihrer Anwendung. Authentication ist **neu** und geht mit dem Release 2026-11-01 in Produktion. ## Basis-URL Jede Anwendung ist ihr eigener OpenID Connect Issuer, und jeder unten aufgeführte Endpoint wird unter dem Stamm dieses Issuers bereitgestellt: - `https://.auth.didit.me` für eine Live-Anwendung oder `https://.sandbox.auth.didit.me` für eine Sandbox-Anwendung. - Ihre eigene benutzerdefinierte Domain, sobald sie aktiv ist. Sie ersetzt dann den Standard-Host als Issuer: Neue Token geben sie in `iss` an, Discovery verweist auf sie und der veröffentlichbare Schlüssel ändert sich. Zugriffstoken, die unter dem Standard-Host ausgestellt wurden, schlagen bei `/session/`, `/step-up/` und `/monitoring-token/` fehl, bis sie aktualisiert werden. Live und Sandbox sind separate Anwendungen, also separate Issuer mit separaten Schlüsseln. Der veröffentlichbare Schlüssel lautet `pk_live_` (Live) oder `pk_test_` (Sandbox), gefolgt von der Base64url-Codierung ohne Padding des Issuers ohne abschließenden Schrägstrich: Decodieren Sie ihn, um den Issuer zu ermitteln. Es handelt sich um eine öffentliche Kennung, nicht um Anmeldedaten. Dieselben JSON-Endpoints werden auch unter `https://apx.didit.me/auth/v2/authentication/{application_id}/` bereitgestellt. Token geben immer den obigen Issuer an, unabhängig davon, welche Adresse sie ausgestellt hat. ## Anmeldedaten Diese Endpoints akzeptieren niemals Ihren Didit-API-Schlüssel oder ein Konsolen-Token. - Discovery, das JWKS und `POST /token/` erfordern keine Anmeldedaten. Clients sind öffentlich: Es gibt kein Client-Secret, und ein Autorisierungscode ist an seinen PKCE-Verifier (`S256`) gebunden. `client_id` ist Ihre Anwendungs-ID. - `/session/`, `/step-up/` und `/monitoring-token/` erfordern das Zugriffstoken der Person: `Authorization: Bearer `. Jeder erfolgreiche Aufruf zählt als Aktivität in der Sitzung und setzt daher den Inaktivitäts-Timeout der Sitzung zurück. ## Request-Bodys Jeder Endpoint, der einen Body akzeptiert, unterstützt JSON-, form-codierte und multipart-Bodys. Dieses Dokument führt JSON sowie form-codierte Anfragen für `POST /token/` auf, wie es von OAuth-Clients gesendet wird. Ein Feld, das der Endpoint nicht akzeptiert, führt zu `400 {"": "unknown_field"}`. ## Token - **Access-Token**: ein ES256-JWT mit dem Header `typ: at+jwt`, maximal 5 Minuten gültig und niemals länger als seine Sitzung. Claims: `AccessTokenClaims`. - **ID-Token**: ein ES256-JWT mit dem Header `typ: JWT`. Claims: `IDTokenClaims`. Es wird niemals als Zugriffstoken akzeptiert. - **Refresh-Token**: eine zufällige Zeichenfolge, die bei jeder Verwendung rotiert. Das erneute Senden eines bereits verwendeten Refresh-Tokens widerruft die Sitzung. Verifizieren Sie ein Token mit den Schlüsseln aus `GET /.well-known/jwks.json`: Der Algorithmus muss `ES256` sein, `typ` muss mit dem Token-Typ übereinstimmen, `iss` muss dem von Ihnen konfigurierten Issuer entsprechen und `aud` Ihrer Anwendungs-ID. Eine Offline-Verifizierung erkennt eine widerrufene Sitzung erst nach Ablauf ihres Zugriffstokens; `GET /session/` ist die sofortige Prüfung. ## Fehler | Body | Wann | | --- | --- | | `{"error": ""}` | Fehler von `POST /token/`, alle mit Status `400`, im Body-Format von [RFC 6749 Abschnitt 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client` und Didits `mfa_required`. Dienstfehler: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` oder `{"": ""}` | Ein Anfragefeld hat die Validierung nicht bestanden. `non_field_errors` benennt eine feldübergreifende Regel und `unknown_field` ein Feld, das der Endpoint nicht akzeptiert. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (unbekannte Anwendung oder Step-Up) und `429` (Rate-Limit). Außerdem `400` für einen Body, der nicht geparst werden kann (`JSON parse error - ...`), `405` für eine Methode, die der Endpoint nicht bedient, und `415` für einen nicht unterstützten `Content-Type`. | Ein `401` enthält außerdem `WWW-Authenticate: Bearer`, und ein `429` enthält `Retry-After` in Sekunden. Zwei Ablehnungen erfolgen nicht als JSON. Eine Adresse, die kein Issuer ist, wird abgelehnt, bevor sie diese Endpoints erreicht, beispielsweise mit einer leeren `404`-Antwort für einen ungenutzten `*.auth.didit.me`-Namen. Eine `step_up_id`, die keine UUID ist, erhält eine `404`-Seite. ## Rate-Limits Eine Anfrage muss zwei Ebenen durchlaufen. **Endpoint-Limits**, gezählt pro Client-IP-Adresse, pro Anwendung und pro Endpoint: - Discovery und das JWKS: 1.200 Anfragen pro Minute und 12.000 pro Stunde. - Jeder andere Endpoint: 30 Anfragen pro Minute und 300 pro Stunde. `GET` und `DELETE /session/` teilen sich eine Zählung. Bei Überschreitung eines Limits: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, oder `3600 seconds` für das stündliche Limit. **Bot-Schutz**, bei jedem `POST` und `DELETE`. Seine Buckets werden von allen `POST`- und `DELETE`-Anfragen der Anwendung geteilt, einschließlich der gehosteten Anmeldeschritte, und füllen sich kontinuierlich wieder auf: - 60 Anfragen pro Minute pro Client-IP-Adresse. - 30 Anfragen pro Minute pro Gerät für Anfragen, die ihr Gerät identifizieren, wie dies bei Browsern und nativen SDKs der Fall ist. - 3.000 Anfragen pro Minute für die gesamte Anwendung über alle IP-Adressen hinweg. Token-Aktualisierungen (`POST /token/` mit `grant_type=refresh_token`) greifen stattdessen auf einen eigenen Bucket zu: 6.000 pro Minute für die gesamte Anwendung. Bei Überschreitung eines Buckets: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` wenn N gleich 1 ist). Der Bucket pro IP erstreckt sich über alle Endpoints, sodass eine einzelne Adresse, die Token-, Step-Up- und Abmeldeaufrufe mischt, ihn leeren kann, bevor sie ein Endpoint-Limit erreicht. Der Anwendungs-Bucket zählt jeden Client der Anwendung, einschließlich Browsern. Beide Ebenen antworten, bevor der Endpoint ausgeführt wird. Eine Anfrage, die `429` erhalten hat, wurde also nicht ausgeführt: Wiederholen Sie sie nach `Retry-After`, einschließlich einer Token-Aktualisierung. ## Browser-Anfragen Eine Anfrage, die einen `Origin`-Header enthält, muss von einem der anwendungseigenen Origins oder ihren erlaubten Origins stammen, andernfalls erhält sie `403 origin_not_allowed`. Server-zu-Server-Anfragen senden keinen `Origin`-Header. ## Hier nicht behandelt Diese Routen bedienen die gehosteten Seiten, die Browser- und nativen SDKs sowie KI-Agenten. Sie sind nicht Teil des Serververtrags und werden von Server-SDKs nicht aufgerufen: - Anmeldeschritte: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*` und `/protection/complete/`. - Gehostete Seiten und Callbacks: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/` und die nativen App-Zuordnungsdateien unter `/.well-known/`. - Agentenzugriff: `/agents/*` und `/grants/`, einschließlich `GET /agents/session/`, der Live-Prüfung für das Zugriffstoken eines KI-Agenten. Agentenzugriff ist nicht Teil dieser Version des Vertrags. - Die Konsolen-Verwaltungs-API für Authentication, die Konsolensitzungen verwendet. Authentication-Ereignisse werden derzeit noch nicht als Webhooks zugestellt, daher definiert dieses Dokument keinen Webhook. servers: - url: https://{issuer} description: 'Der Aussteller Ihrer Anwendung: ihr Anmeldeursprung.' variables: issuer: default: your-app.auth.didit.me description: >- Der Host des Ausstellers: `.auth.didit.me` (Produktion), `.sandbox.auth.didit.me` (Sandbox) oder Ihre aktive benutzerdefinierte Domain. security: [] tags: - name: Issuer description: Discovery- und Signaturschlüssel zur Überprüfung von Tokens. - name: Tokens description: Der Autorisierungscode und Refresh-Grants. - name: Sessions description: Die Sitzung hinter einem Zugriffstoken prüfen und beenden. - name: Step-ups description: Verifizierung vor einer sensiblen Aktion. - name: Monitoring description: Geräte-Anmeldedaten für Transaktionsüberwachungs-Ereignisse. paths: /session/: get: tags: - Sessions summary: Sitzung abrufen description: >- Prüft das Zugriffstoken anhand der Live-Sitzung und gibt es zurück. Strenger als die eigenständige Überprüfung des JWT: Sie schlägt auch sofort fehl, wenn die Sitzung widerrufen wurde, inaktiv wurde oder ihre Lebensdauer abgelaufen ist, wenn die Person gesperrt wurde oder ihre E-Mail-Adresse nicht mehr verifiziert ist, wenn die Sitzung Ihre MFA-Richtlinie nicht mehr erfüllt (beispielsweise nachdem die Person eine Authentifikator-App hinzugefügt hat oder Administrator einer Organisation geworden ist) oder wenn das Token durch einen Refresh ersetzt wurde. Nutzen Sie dies vor einer sensiblen Aktion, beispielsweise einer Auszahlung. Eine erfolgreiche Prüfung gilt als Aktivität und setzt somit das Inaktivitäts-Timeout der Sitzung zurück. operationId: authentication_get_session responses: '200': description: Die Sitzung ist aktiv. headers: Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Session' examples: Session: summary: Eine Passwort-Sitzung value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - password mfa_verified: false email: person@example.com email_verified: true phone: null verified_identity: null verified: null expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: '' organizations: [] VerifiedMember: summary: Ein verifiziertes Organisationsmitglied value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - passkey mfa_verified: true email: person@example.com email_verified: true phone: '+34600000000' verified_identity: null verified: level: full_id over_18: true given_name: Alex country: ES expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: https://app.example.com/ organizations: - organization_id: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: Northwind role: admin custom_role: null '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: Session: type: object description: Die Live-Sitzung hinter einem Zugriffstoken. required: - sub - sid - application_id - vendor_data - amr - mfa_verified - email - email_verified - phone - verified_identity - verified - expires_at - post_logout_redirect_uri - organizations properties: sub: type: string format: uuid description: Die Identitäts-ID. example: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: type: string format: uuid description: Die Sitzungs-ID. example: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: type: string format: uuid example: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: type: string description: >- Die Referenz der Person über Didit-Produkte hinweg, wie in den Tokens. example: user-42 amr: $ref: '#/components/schemas/AuthenticationMethods' mfa_verified: type: boolean description: >- Gibt an, ob die Sitzung einen zweiten Faktor bestanden hat. Bei einer Passkey-Anmeldung immer `true`. example: false email: type: string format: email nullable: true example: person@example.com email_verified: type: boolean example: true phone: type: string nullable: true description: Telefonnummer im Format E.164 oder `null`. example: null verified_identity: $ref: '#/components/schemas/WalletVerification' verified: type: object nullable: true description: >- Verifizierungsstufe und ausgewählte Claims; dasselbe Objekt, das die Tokens als `verified` tragen, oder `null`, wenn keine vorhanden sind. Lesen Sie diesen Wert und nicht `email_verified`, um zu erfahren, ob die Person ihre Identität verifiziert hat. properties: level: type: string enum: - liveness - liveness_face_match - full_id description: >- Die höchste bestandene Stufe. Von der schwächsten zur stärksten: `liveness`, `liveness_face_match`, `full_id`. example: full_id over_18: type: boolean example: true over_21: type: boolean example: true given_name: type: string example: Alex family_name: type: string example: Doe birthdate: type: string description: Geburtsdatum aus dem Dokument, `YYYY-MM-DD`. example: '1990-04-12' nationality: type: string description: ISO 3166-1 Alpha-2-Ländercode. example: ES country: type: string description: ISO 3166-1 Alpha-2-Code des Landes des Dokuments. example: ES document_verified: type: boolean example: true liveness: type: boolean example: true expires_at: type: string format: date-time description: >- Wann die Sitzung spätestens endet. Ein Inaktivitäts-Timeout kann sie früher beenden. example: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: type: string description: >- Wohin Ihre Anwendung die Person nach der Abmeldung weiterleitet. Leere Zeichenfolge, wenn nicht festgelegt. example: https://app.example.com/ organizations: type: array description: >- Jede Kundenorganisation, zu der die Person gehört, wenn Organisationen aktiviert sind. Andernfalls leer. items: $ref: '#/components/schemas/SessionOrganization' AuthenticationMethods: type: array description: >- Welche Anmeldemethode die Sitzung verwendet hat, als einzelner Wert: beispielsweise `password`, `code` (E-Mail-Code), `magic` (Magic Link), `passkey`, `phone`, `sso`, `wallet` (Didit ID Wallet) oder der Name einer Social-Sign-in-Methode. Leer bei einem Agenten-Token. items: type: string example: - password WalletVerification: type: object description: >- Was die Didit ID Wallet bei der Anmeldung geteilt hat. `null`, wenn sich die Person auf andere Weise angemeldet hat. nullable: true required: - issuer - subject properties: issuer: type: string description: Der Aussteller der Wallet. example: https://apx.didit.me/auth/idv subject: type: string description: Die ID der Person bei der Wallet. example: 8b7f5c1e-2d3a-4b5c-9e8f-7a6b5c4d3e2f shared_session: type: object description: >- Eine Verifizierung, die die Person geteilt hat und die Sie mit Ihrem eigenen API-Schlüssel einlösen. properties: share_token: type: string session_id: type: string from_application_id: type: string claims: type: object description: >- Die verifizierten Angaben, deren Weitergabe die Person zugestimmt hat, beschränkt auf das, was Ihre Anwendung angefordert hat. additionalProperties: oneOf: - type: boolean - type: string example: over_18: true given_name: Alex SessionOrganization: type: object required: - organization_id - organization__name - role - custom_role properties: organization_id: type: string format: uuid example: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: type: string description: Der Name der Organisation. example: Northwind role: type: string enum: - admin - member - billing example: admin custom_role: type: object nullable: true description: Die dem Mitglied zugewiesene benutzerdefinierte Rolle oder `null`. required: - key - permissions properties: key: type: string example: approver permissions: type: array items: type: string example: - payouts.approve Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: Ein OAuth-Fehler (RFC 6749 Abschnitt 5.2) oder ein Dienstfehler. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- Das Zugriffstoken fehlt, ist fehlerhaft, abgelaufen, von einem anderen Aussteller oder Schlüssel signiert, ein ID-Token, ein Agent-Token oder wurde durch einen Refresh ersetzt; oder seine Sitzung wurde widerrufen, ist wegen Inaktivität abgelaufen, hat ihre Lebensdauer überschritten oder erfüllt Ihre MFA-Richtlinie nicht mehr, oder die Person wurde gesperrt bzw. ihre E-Mail ist nicht mehr verifiziert. Leiten Sie die Person erneut durch die Anmeldung. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Abgelehntes Zugriffstoken value: detail: invalid_token OriginNotAllowed: description: >- Die Anfrage enthielt einen `Origin`, der weder der anwendungseigene ist noch zu den zulässigen Origins gehört. Server-Anfragen senden keinen `Origin`. headers: Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Origin nicht zulässig value: detail: origin_not_allowed ApplicationNotFound: description: >- Die Adresse gehört zu einer Anwendung, aber Authentication ist für sie nicht aktiv; bei der Adresse `apx.didit.me` ist die Anwendungs-ID unbekannt. Eine Adresse, die zu keiner Anwendung gehört, wird abgewiesen, bevor sie den Endpoint erreicht, und diese Antwort ist kein JSON. headers: Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: ApplicationNotFound: summary: Unbekannte Anwendung value: detail: No Configuration matches the given query. RateLimited: description: >- Zu viele Anfragen von dieser IP-Adresse für diesen Endpoint, oder bei einem `POST` oder `DELETE` ist ein Bot-Schutz-Bucket leer. Es wurde nichts ausgeführt: Warten Sie `Retry-After` Sekunden und versuchen Sie es dann erneut. headers: Retry-After: description: Sekunden, die vor einem Wiederholungsversuch gewartet werden müssen. schema: type: integer example: 60 Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Endpoint-Limit value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Bot-Schutz-Limit (POST und DELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- Ein Dienst, von dem die Anfrage abhängt, ist vorübergehend nicht verfügbar. Versuchen Sie es mit Backoff erneut. headers: Cache-Control: description: 'Immer `no-store`: Diese Antwort niemals zwischenspeichern.' schema: type: string example: no-store Pragma: description: Immer `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: Später erneut versuchen value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- Das Access Token der Person von `POST /token/`: ein ES256-JWT mit dem Header `typ: at+jwt`, gültig für maximal 5 Minuten. Nicht Ihr Didit-API-Schlüssel. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.