Organisations-API

Organisationen sind die B2B-Multi-Tenancy-Schicht in Auris. Eine Organisation repräsentiert ein Kundenunternehmen innerhalb deines Tenants — mit eigenen Mitgliedern, Rollen, SSO-Konfiguration und Domain-Verifizierung. Benutzer können mehreren Organisationen mit unterschiedlichen Rollen in jeder angehören.

Organisationsmitgliedsrollen: OWNER (vollständige Kontrolle), ADMIN (Mitglieder und Einstellungen verwalten), MEMBER (Standardzugriff), VIEWER (Nur-Lesen).

Alle Endpunkte erfordern den x-tenant-Header und die manage:organizations-Berechtigung, sofern nicht anders angegeben.

Organisations-CRUD

GET/api/organizationsRequires: manage:organizations

Alle Organisationen im Tenant auflisten. Gibt zusammenfassende Informationen zurück, einschließlich Mitgliederzahl und ob eine SSO-Verbindung konfiguriert ist.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20)
`search`	string	Nach Organisationsname oder Anzeigename suchen

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "org_abc123",
        "name": "acme-gmbh",
        "displayName": "Acme GmbH",
        "memberCount": 45,
        "hasSso": true,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 }
  }
}

POST/api/organizationsRequires: manage:organizations

Eine neue Organisation erstellen. Der name ist ein maschinenlesbarer Bezeichner (Kleinbuchstaben, Bindestriche erlaubt), der im Tenant eindeutig sein muss. Der displayName ist der menschenlesbare Name, der in der Benutzeroberfläche angezeigt wird.

Anforderungs-Body


{
  "name": "acme-gmbh",
  "displayName": "Acme GmbH",
  "metadata": {
    "industry": "Fertigung",
    "country": "DE"
  }
}

displayName und metadata sind optional.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "org_def456",
    "name": "acme-gmbh",
    "displayName": "Acme GmbH",
    "metadata": { "industry": "Fertigung", "country": "DE" },
    "memberCount": 0,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NAME_TAKEN`	409	Eine Organisation mit diesem Namen existiert bereits
`VALIDATION_ERROR`	400	Ungültiger Organisationsname (muss kleingeschriebene alphanumerische Zeichen mit Bindestrichen sein)

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

Vollständige Details für eine Organisation abrufen, einschließlich Metadaten und SSO-Status.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "name": "acme-gmbh",
    "displayName": "Acme GmbH",
    "metadata": { "industry": "Fertigung" },
    "memberCount": 45,
    "hasSso": true,
    "ssoProvider": "saml",
    "verifiedDomains": ["acme-gmbh.de"],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-02-01T12:00:00Z"
  }
}

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

Den Anzeigenamen oder die Metadaten einer Organisation aktualisieren. Der name (Maschinenbezeichner) kann nach der Erstellung nicht geändert werden.

Anforderungs-Body


{
  "displayName": "Acme GmbH International",
  "metadata": {
    "industry": "Fertigung",
    "country": "DE",
    "tier": "enterprise"
  }
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "displayName": "Acme GmbH International",
    "metadata": { "industry": "Fertigung", "country": "DE", "tier": "enterprise" }
  }
}

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

Eine Organisation löschen. Alle Mitglieder werden aus der Organisation entfernt. SSO-Verbindungen und Domain-Verifizierungen werden gelöscht. Benutzerkonten selbst werden nicht gelöscht.

Erfolgsantwort


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

Mitgliederverwaltung

GET/api/organizations/[id]/membersRequires: manage:organizations

Alle Mitglieder einer Organisation mit ihren Rollen und Beitrittsdaten auflisten.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20)
`role`	`OWNER` \| `ADMIN` \| `MEMBER` \| `VIEWER`	Nach Rolle filtern

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "userId": "usr_abc123",
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Müller",
        "role": "ADMIN",
        "joinedAt": "2025-01-15T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 45, "totalPages": 3 }
  }
}

POST/api/organizations/[id]/membersRequires: manage:organizations

Einen bestehenden Benutzer (nach Benutzer-ID) mit einer bestimmten Rolle zur Organisation hinzufügen. Um Benutzer hinzuzufügen, die noch kein Konto haben, verwende stattdessen die Einladungsendpunkte.

Anforderungs-Body


{
  "userId": "usr_abc123",
  "role": "MEMBER"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "MEMBER",
    "joinedAt": "2025-02-18T11:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`USER_NOT_FOUND`	404	Benutzer existiert nicht in diesem Tenant
`ALREADY_MEMBER`	409	Benutzer ist bereits Mitglied dieser Organisation

PATCH/api/organizations/[id]/members/[userId]Requires: manage:organizations

Die Rolle eines Mitglieds innerhalb der Organisation aktualisieren. Nur OWNER- und ADMIN-Mitglieder können geändert werden. Eine Organisation muss immer mindestens einen OWNER haben.

Anforderungs-Body


{
  "role": "ADMIN"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "ADMIN",
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`LAST_OWNER`	400	Der letzte OWNER kann nicht aus einer Organisation entfernt werden

DELETE/api/organizations/[id]/members/[userId]Requires: manage:organizations

Ein Mitglied aus der Organisation entfernen. Das Benutzerkonto wird nicht gelöscht.

Erfolgsantwort


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

Einladungen

GET/api/organizations/[id]/invitationsRequires: manage:organizations

Alle ausstehenden Einladungen für eine Organisation auflisten.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "inv_abc123",
        "email": "[email protected]",
        "role": "MEMBER",
        "status": "pending",
        "expiresAt": "2025-02-25T10:00:00Z",
        "createdAt": "2025-02-18T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
  }
}

Einladungsstatus: pending, accepted, expired, cancelled.

POST/api/organizations/[id]/invitationsRequires: manage:organizations

Einen Benutzer per E-Mail zur Organisation einladen. Eine Einladungs-E-Mail wird mit einem tokenbasierten Akzeptier-Link gesendet. Einladungen laufen nach 7 Tagen ab. Wenn die E-Mail bereits mit einem Tenant-Benutzer verknüpft ist, wird er direkt benachrichtigt. Wenn nicht, wird er aufgefordert, zunächst ein Konto zu erstellen.

Anforderungs-Body


{
  "email": "[email protected]",
  "role": "MEMBER"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "inv_def456",
    "email": "[email protected]",
    "role": "MEMBER",
    "expiresAt": "2025-02-25T10:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`ALREADY_MEMBER`	409	Diese E-Mail ist bereits aktives Mitglied dieser Organisation
`INVITATION_PENDING`	409	Eine ausstehende Einladung existiert bereits für diese E-Mail

DELETE/api/organizations/[id]/invitations/[invId]Requires: manage:organizations

Eine ausstehende Einladung stornieren. Der Einladungslink in der E-Mail wird sofort ungültig.

Erfolgsantwort


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

Enterprise SSO

Enterprise SSO (Single Sign-On) ermöglicht es Organisationsmitgliedern, sich mit ihrem bestehenden Identitätsanbieter (IdP) zu authentifizieren — entweder SAML 2.0 oder OIDC-basiert. SSO-Verbindungen sind auf eine Organisation beschränkt und werden automatisch ausgelöst, wenn Benutzer sich mit einer verifizierten Domain-E-Mail anmelden.

Alle SSO-Endpunkte erfordern manage:sso_connections.

GET/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Alle für eine Organisation konfigurierten SSO-Verbindungen auflisten.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml",
      "domains": ["acme-gmbh.de"],
      "createdAt": "2025-01-20T09:00:00Z"
    }
  ]
}

SSO-Verbindungsstatus: PENDING (konfiguriert, aber nicht aktiviert), ACTIVE, DISABLED, ERROR.

POST/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Eine neue SSO-Verbindung erstellen. Für SAML die IdP-Metadaten-URL oder rohe XML bereitstellen. Für OIDC die Discovery-URL und Client-Anmeldeinformationen bereitstellen.

Anforderungs-Body — SAML


{
  "type": "saml",
  "name": "Acme Unternehmens-IdP",
  "config": {
    "metadataUrl": "https://idp.acme-gmbh.de/metadata",
    "entityId": "https://idp.acme-gmbh.de",
    "ssoUrl": "https://idp.acme-gmbh.de/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\n..."
  }
}

Anforderungs-Body — OIDC


{
  "type": "oidc",
  "name": "Acme OIDC",
  "config": {
    "discoveryUrl": "https://login.acme-gmbh.de/.well-known/openid-configuration",
    "clientId": "auris-sp-client",
    "clientSecret": "sp-client-secret"
  }
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://ihre-auris-domain.de/api/auth/sso/callback",
    "entityId": "https://ihre-auris-domain.de"
  }
}

Die acsUrl (Assertion Consumer Service URL) und entityId sind Werte, die du dem IdP bei der SP-Konfiguration bereitstellst.

POST/api/organizations/[orgId]/sso/connections/[id]/activateRequires: manage:sso_connections

Eine SSO-Verbindung aktivieren. Nach der Aktivierung werden Benutzer mit einer verifizierten Domain-E-Mail beim Login automatisch zum SSO-Anbieter weitergeleitet.

Anforderung: Kein Body erforderlich.

Erfolgsantwort


{
  "ok": true,
  "data": { "activated": true, "status": "ACTIVE" }
}

POST/api/organizations/[orgId]/sso/connections/[id]/deactivateRequires: manage:sso_connections

Eine SSO-Verbindung deaktivieren. Benutzer mit Domain-E-Mails fallen auf die Standard-Passwort- Authentifizierung zurück, bis SSO wieder aktiviert wird.

Anforderung: Kein Body erforderlich.

Erfolgsantwort


{
  "ok": true,
  "data": { "deactivated": true, "status": "DISABLED" }
}

Domain-Verifizierung

Die Domain-Verifizierung beweist, dass du eine Domain kontrollierst, bevor die SSO-basierte automatische Weiterleitung für E-Mail-Adressen auf dieser Domain aktiviert wird. Die Verifizierung erfolgt über einen DNS-TXT-Eintrag.

GET/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Alle mit der SSO-Konfiguration einer Organisation verbundenen Domains auflisten, einschließlich Verifizierungsstatus.

Erfolgsantwort


{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-gmbh.de",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z"
    }
  ]
}

Domain-Verifizierungsstatus: PENDING, VERIFYING, ACTIVE, FAILED.

POST/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Eine Domain hinzufügen und die Verifizierung einleiten. Ein verificationToken wird zurückgegeben, das als DNS-TXT-Eintrag auf der Domain hinzugefügt werden muss. Dann rufe den Prüfungsendpunkt auf, um zu bestätigen.

Anforderungs-Body


{
  "domain": "acme-gmbh.de"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "dom_def456",
    "domain": "acme-gmbh.de",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-ghi789jkl012",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-gmbh.de",
      "value": "auris-verify-ghi789jkl012"
    }
  }
}

Füge den in dnsRecord angezeigten DNS-TXT-Eintrag bei deinem Domain-Registrar hinzu, dann rufe den Prüfungsendpunkt auf.

POST/api/organizations/[orgId]/sso/domains/[id]/checkRequires: manage:sso_connections

Die DNS-Verifizierung für eine Domain auslösen. Auris führt eine Live-DNS-TXT-Abfrage durch, um nach dem Verifizierungstoken zu suchen. Gibt den neuen Status sofort zurück.

Anforderung: Kein Body erforderlich.

Erfolgsantwort — verifiziert


{
  "ok": true,
  "data": {
    "domain": "acme-gmbh.de",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Erfolgsantwort — noch nicht propagiert


{
  "ok": true,
  "data": {
    "domain": "acme-gmbh.de",
    "status": "PENDING",
    "message": "TXT-Eintrag noch nicht gefunden. DNS-Propagation kann bis zu 48 Stunden dauern."
  }
}

Die DNS-Propagation dauert in der Regel Minuten, kann aber in seltenen Fällen bis zu 48 Stunden dauern. Rufe den Prüfungsendpunkt regelmäßig auf, bis der Status auf ACTIVE wechselt.

Zugehörige Referenzen

Multi-Tenancy — Wie Organisationen Auris-Tenants zugeordnet werden
B2B-Multi-Tenant-Leitfaden — Multi-Organisations-Architektur einrichten
Enterprise SSO — SSO für Organisationsmitglieder konfigurieren
Organisationen — Organisationen über die Konsole verwalten
SSO-API — Enterprise-SSO-Verbindungsendpunkte