API-Referenz

Die Auris-API ist eine REST-API, die programmatischen Zugriff auf alle IAM-Funktionen bietet: Authentifizierung, Benutzerverwaltung, Rollen, Berechtigungen, Organisationen, feingranulare Autorisierung und mehr. Alle API-Antworten verwenden JSON.

Basis-URL

https://ihre-auris-domain.de/api

Ersetze ihre-auris-domain.de durch die Domain, auf der deine Auris-Instanz bereitgestellt wird. Wenn du den Auris-Cloud-Dienst verwendest, ist deine Domain die in der Konsole unter Einstellungen → Benutzerdefinierte Domains angezeigte.

Authentifizierung

Bearer-Token

Die meisten Endpunkte erfordern ein gültiges Zugriffs-Token im Authorization-Header:

Authorization: Bearer <zugriffs_token>

Zugriffs-Token sind kurzlebige JWTs (Standard 15 Minuten), die über die Authentifizierungsendpunkte erhalten werden. Sie werden mit RS256 (oder HS256 je nach Konfiguration) signiert und können lokal mit dem JWKS-Endpunkt verifiziert werden.

Zugriffsstufe nach Endpunkttyp

Tenant-Header

Auris ist eine Multi-Tenant-Plattform. Anforderungen an Admin-Endpunkte müssen den Tenant-Bezeichner enthalten:

x-tenant: <tenant-id>

Die Tenant-ID ist der in deiner Auris-Bereitstellung konfigurierte Realm-Name. Für die Standardinstallation ist es default. Für benutzerdefinierte Tenant-Setups ist es der in der Konsole unter Einstellungen → Allgemein angezeigte Realm-Name.

Wenn der Header bei Endpunkten, die ihn erfordern, weggelassen wird, gibt die API 400 Bad Request mit Code MISSING_TENANT zurück.

Anforderungsformat

Verwende Content-Type: application/json für alle POST-, PUT- und PATCH-Anforderungen mit einem Anforderungs-Body:

Content-Type: application/json

Beispielanforderung:

curl -X POST https://ihre-auris-domain.de/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "geheim"}'

Für Datei-Uploads (Benutzerimport) verwende multipart/form-data.

Antwortformat

Alle API-Antworten folgen einem konsistenten Umschlagsformat.

Erfolgsantwort

{
  "ok": true,
  "data": { }
}

Das data-Feld enthält das Ergebnis. Seine Form variiert je nach Endpunkt und ist für jeden Endpunkt individuell dokumentiert.

Fehlerantwort

{
  "ok": false,
  "error": {
    "code": "FEHLERCODE",
    "message": "Für Menschen lesbare Beschreibung des Problems."
  }
}

HTTP-Statuscodes

Häufige Fehlercodes

Paginierung

Listen-Endpunkte geben paginierte Ergebnisse mit cursorbasierter Seitennummerierung zurück.

Antwortform

{
  "ok": true,
  "data": {
    "data": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Abfrageparameter

Beispiel:

GET /api/users?page=2&limit=50

Rate Limiting

Jede Antwort enthält Rate-Limiting-Header:

Wenn ein Rate-Limit überschritten wird, gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück, der angibt, wie viele Sekunden gewartet werden soll.

Rate-Limit-Stufen

CORS

Cross-Origin Resource Sharing (CORS) wird für alle API-Endpunkte durchgesetzt. Erlaubte Origins müssen in den Anwendungseinstellungen in der Auris-Konsole unter Anwendungen → [App] → Erlaubte Origins registriert werden.

Preflight-OPTIONS-Anforderungen werden automatisch behandelt. Anmeldedaten (Cookies) sind erlaubt, wenn die Anforderungsorigin registriert ist.

Eine Origin registrieren:

1. Gehe zu Konsole → Anwendungen
2. Wähle deine Anwendung aus
3. Füge die Origin zu Erlaubte Origins hinzu (z. B. https://app.ihredomain.de)

OIDC-Discovery

Auris stellt ein Standard-OpenID-Connect-Discovery-Dokument bereit:

GET /.well-known/openid-configuration

Dies gibt ein JSON-Dokument zurück, das alle Endpunkt-URLs, unterstützte Grant-Typen, Scopes, Signaturalgorithmen und andere Metadaten enthält. Standard-OIDC-Bibliotheken verwenden dies zur automatischen Konfiguration.

Beispiel-Antwortfelder:

{
  "issuer": "https://ihre-auris-domain.de",
  "authorization_endpoint": "https://ihre-auris-domain.de/api/oauth/authorize",
  "token_endpoint": "https://ihre-auris-domain.de/api/auth/token",
  "userinfo_endpoint": "https://ihre-auris-domain.de/api/auth/validate",
  "jwks_uri": "https://ihre-auris-domain.de/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "HS256"],
  "scopes_supported": ["openid", "profile", "email"]
}

JWKS

Öffentliche Signaturschlüssel zur JWT-Verifizierung sind verfügbar unter:

GET /.well-known/jwks.json

Antwort:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Schlüssel werden von Clients bis zu 1 Stunde gecacht (Cache-Control: public, max-age=3600). Key-Rotation fügt dem Set einen neuen Schlüssel hinzu; alte Schlüssel bleiben vorhanden, bis ihre ausgestellten Token ablaufen.

SDK-Clients

Anstatt die API direkt aufzurufen, erwäge die Verwendung eines Auris-SDK, das Token-Management, PKCE, Aktualisierung und Fehlerbehandlung automatisch übernimmt:

Siehe die SDK-Dokumentation für Installations- und Verwendungsanleitungen.