Anwendungs-API

Anwendungen in Auris repräsentieren Client-Apps oder -Dienste, die mit der IAM-Plattform integriert sind — Web-Apps, mobile Apps, API-Server, CLIs und Machine-to-Machine-Dienste. Jede Anwendung hat eine Client-ID (immer sichtbar) und optional ein Client-Secret (für vertrauliche Clients). Auris unterstützt vier Anwendungstypen: WEB, MOBILE, API und M2M.

Alle Endpunkte in diesem Abschnitt erfordern die manage:applications-Berechtigung und den x-tenant-Header.

Anwendungs-CRUD

GET/api/applicationsRequires: manage:applications

Alle im Tenant registrierten Anwendungen auflisten. Gibt zusammenfassende Informationen für jede Anwendung zurück, einschließlich Typ, Client-ID, erlaubter Redirect-URIs und Erstellungsdatum.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20)
`type`	`WEB` \| `MOBILE` \| `API` \| `M2M`	Nach Anwendungstyp filtern
`search`	string	Nach Anwendungsname suchen

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "app_abc123",
        "name": "Meine Web-App",
        "type": "WEB",
        "clientId": "cid_abc123",
        "redirectUris": ["https://app.ihredomain.de/callback"],
        "allowedOrigins": ["https://app.ihredomain.de"],
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

POST/api/applicationsRequires: manage:applications

Eine neue Anwendung erstellen. Für die Typen WEB und MOBILE sollten redirectUris angegeben werden. Für den Typ M2M sind redirectUris nicht erforderlich, aber M2M-Scopes sollten separat konfiguriert werden. Ein clientSecret wird automatisch generiert und nur in der Erstellungsantwort zurückgegeben — speichere es sicher. Es kann nicht erneut abgerufen werden; verwende die Secret-Rotation, um ein neues zu generieren.

Anforderungs-Body


{
  "name": "Mein Dashboard",
  "type": "WEB",
  "redirectUris": [
    "https://app.ihredomain.de/callback",
    "http://localhost:3000/callback"
  ],
  "allowedOrigins": [
    "https://app.ihredomain.de",
    "http://localhost:3000"
  ]
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "app_def456",
    "name": "Mein Dashboard",
    "type": "WEB",
    "clientId": "cid_def456",
    "clientSecret": "cs_sk_...",
    "redirectUris": ["https://app.ihredomain.de/callback", "http://localhost:3000/callback"],
    "allowedOrigins": ["https://app.ihredomain.de", "http://localhost:3000"],
    "createdAt": "2025-02-18T12:00:00Z"
  }
}

Das clientSecret wird nur einmal bei der Erstellung zurückgegeben. Speichere es sofort. Für öffentliche Clients (Browser-SPAs und mobile Apps) verwende das clientSecret nicht — verwende stattdessen PKCE.

Fehlercodes

Code	HTTP	Beschreibung
`NAME_TAKEN`	409	Eine Anwendung mit diesem Namen existiert bereits
`VALIDATION_ERROR`	400	Ungültiges Redirect-URI-Format oder fehlendes Pflichtfeld

GET/api/applications/[id]Requires: manage:applications

Vollständige Details für eine einzelne Anwendung abrufen, einschließlich aller Konfigurationsfelder. Das clientSecret wird nach der Erstellung nie zurückgegeben — verwende die Rotation, um ein neues zu generieren.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "Meine Web-App",
    "type": "WEB",
    "clientId": "cid_abc123",
    "redirectUris": ["https://app.ihredomain.de/callback"],
    "allowedOrigins": ["https://app.ihredomain.de"],
    "enableDeviceFlow": false,
    "enableCiba": false,
    "enableDpop": false,
    "enableM2m": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-02-01T15:30:00Z"
  }
}

PUT/api/applications/[id]Requires: manage:applications

Die Konfiguration einer Anwendung aktualisieren. Alle Felder sind optional — nur bereitgestellte Felder werden aktualisiert.

Anforderungs-Body


{
  "name": "Meine Web-App v2",
  "redirectUris": [
    "https://app.ihredomain.de/callback",
    "https://staging.ihredomain.de/callback"
  ],
  "allowedOrigins": [
    "https://app.ihredomain.de",
    "https://staging.ihredomain.de"
  ],
  "enableDeviceFlow": false
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "Meine Web-App v2",
    "redirectUris": [
      "https://app.ihredomain.de/callback",
      "https://staging.ihredomain.de/callback"
    ]
  }
}

DELETE/api/applications/[id]Requires: manage:applications

Eine Anwendung löschen. Dadurch werden alle für die Anwendung ausgestellten aktiven Tokens widerrufen. Diese Aktion kann nicht rückgängig gemacht werden.

Erfolgsantwort


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

Secret-Rotation

PATCH/api/applications/[id]?action=rotate-secretRequires: manage:applications

Ein neues Client-Secret für die Anwendung generieren, wodurch das vorherige sofort ungültig wird. Das neue Secret wird einmal zurückgegeben. Alle Integrationen, die das alte Secret verwenden, müssen aktualisiert werden.

Die Rotation des Secrets macht das vorherige sofort ungültig. Aktive M2M-Tokens, die mit dem alten Secret erhalten wurden, funktionieren weiterhin bis zum Ablauf, aber neue Tokens können nicht mehr abgerufen werden.

Anforderung: Kein Body erforderlich.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "clientId": "cid_abc123",
    "clientSecret": "cs_sk_neu...",
    "rotatedAt": "2025-02-18T14:00:00Z"
  }
}

Benutzerdefinierte JWT-Claims

Benutzerdefinierte Claims ermöglichen es, zusätzliche Daten in Zugriffs-Token einzufügen, die von einer bestimmten Anwendung ausgestellt werden. Claims werden zum Zeitpunkt der Token-Ausstellung aufgelöst und in den JWT-Payload eingebettet.

Werttypen

Typ	Beschreibung	Beispiel
`STATIC`	Fester Zeichenkettenwert	`"plan": "enterprise"`
`USER_ATTRIBUTE`	Wert aus dem Profilattribut eines Benutzers	`"email": user.email`
`ROLE_BASED`	Wert, der sich basierend auf den Rollen des Benutzers ändert	`"tier": "admin"` wenn Rolle `admin`
`EXPRESSION`	Benutzerdefinierter Ausdruck, der zur Laufzeit ausgewertet wird	`user.roles.includes('admin') ? 'full' : 'read'`

Reservierte JWT-Claims (sub, iss, aud, exp, iat, jti, type, email, roles) können nicht durch benutzerdefinierte Claims überschrieben werden.

GET/api/applications/[id]/custom-claimsRequires: manage:applications

Alle für eine Anwendung konfigurierten benutzerdefinierten Claims auflisten.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "claim_abc",
      "claimKey": "plan",
      "valueType": "STATIC",
      "staticValue": "enterprise",
      "isActive": true
    },
    {
      "id": "claim_def",
      "claimKey": "orgId",
      "valueType": "USER_ATTRIBUTE",
      "userAttribute": "organizationId",
      "isActive": true
    }
  ]
}

POST/api/applications/[id]/custom-claimsRequires: manage:applications

Einen neuen benutzerdefinierten Claim für eine Anwendung erstellen.

Anforderungs-Body — Statischer Claim


{
  "claimKey": "plan",
  "valueType": "STATIC",
  "staticValue": "enterprise"
}

Anforderungs-Body — Benutzerattribut-Claim


{
  "claimKey": "abteilung",
  "valueType": "USER_ATTRIBUTE",
  "userAttribute": "department"
}

Anforderungs-Body — Rollenbasierter Claim


{
  "claimKey": "accessLevel",
  "valueType": "ROLE_BASED",
  "roleMapping": {
    "admin": "full",
    "editor": "write",
    "viewer": "read"
  }
}

Anforderungs-Body — Ausdrucks-Claim


{
  "claimKey": "isPremium",
  "valueType": "EXPRESSION",
  "expression": "user.roles.includes('premium') || user.roles.includes('admin')"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "claim_ghi",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "enterprise",
    "isActive": true
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`CLAIM_KEY_RESERVED`	400	Claim-Key ist ein reserviertes JWT-Feld
`CLAIM_KEY_TAKEN`	409	Ein Claim mit diesem Key existiert bereits für diese Anwendung

PATCH/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Einen benutzerdefinierten Claim aktualisieren. Unterstützt partielle Updates — nur bereitgestellte Felder werden geändert.

Anforderungs-Body


{
  "staticValue": "professional",
  "isActive": false
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "claim_abc",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "professional",
    "isActive": false
  }
}

DELETE/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Einen benutzerdefinierten Claim löschen. Der Claim wird nach der Löschung nicht mehr in Tokens erscheinen.

Erfolgsantwort


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

POST/api/applications/[id]/custom-claims/previewRequires: manage:applications

Vorschau, wie benutzerdefinierte Claims für einen bestimmten Benutzer aufgelöst würden. Nützlich zum Testen der Claim-Konfiguration ohne Ausstellung eines echten Tokens.

Anforderungs-Body


{
  "userId": "usr_abc123"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "resolvedClaims": {
      "plan": "enterprise",
      "department": "Engineering",
      "accessLevel": "write",
      "isPremium": false
    }
  }
}

M2M-Scopes

M2M-Scopes (Machine-to-Machine) definieren, was ein client_credentials-Token durchführen darf. Scopes sind freie Zeichenketten, die dein Ressourcenserver validiert.

GET/api/applications/[id]/m2m-scopesRequires: manage:applications

Die für eine Anwendung konfigurierten M2M-Scopes auflisten.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "scopes": ["read:users", "manage:roles"],
    "allowedScopes": ["read:users", "manage:roles", "read:audit-logs"]
  }
}

scopes sind die Standard-Scopes, die ausgestellt werden, wenn scope in der Token-Anforderung nicht angegeben wird. allowedScopes sind alle Scopes, die die Anwendung anfordern darf.

POST/api/applications/[id]/m2m-scopesRequires: manage:applications

Die M2M-Scopes für eine Anwendung konfigurieren. Ersetzt die bestehende Scope-Konfiguration vollständig.

Anforderungs-Body


{
  "scopes": ["read:users"],
  "allowedScopes": ["read:users", "read:audit-logs"]
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "scopes": ["read:users"],
    "allowedScopes": ["read:users", "read:audit-logs"]
  }
}

Nach der Aktualisierung der M2M-Scopes bleiben bestehende Tokens mit ihren ursprünglichen Scopes bis zum Ablauf gültig. Neue Token-Anforderungen verwenden die aktualisierte Scope-Konfiguration.

Zugehörige Referenzen

OAuth 2.0 & OIDC — Protokollstandards, die Anwendungen implementieren
Benutzerdefinierte JWT-Claims — Pro-Anwendungs-Claims in Zugriffs-Token konfigurieren
M2M Client Credentials — Server-zu-Server-Authentifizierung für M2M-Apps
Anwendungen — Anwendungen über die Konsole verwalten