Impersonation (Team-Zugriff)

Als Reseller kannst du auf drei Arten auf die Daten deiner verwalteten Teams zugreifen:

X-Tenant-Id Header — Verwende dein eigenes Token zusammen mit einem Mandanten-Kontext-Header (einfach, zustandslos)
Impersonation-Tokens — Erstelle kurzlebige Tokens, die auf den Ziel-Mandanten beschränkt sind (für Automatisierung, kein Header nötig)
SSO-Login-Links — Generiere One-Click-Login-URLs, die Benutzer im Dashboard authentifizieren (für Endbenutzer-Zugriff, kein Passwort nötig)

Method 1: X-Tenant-Id Header

Als Reseller kannst du auf die Daten deiner verwalteten Teams zugreifen, indem du den X-Tenant-Id Header bei jeder API-Anfrage setzt. Damit wird der Datenbank-Kontext umgeschaltet und alle Abfragen laufen im Kontext des Ziel-Mandanten.

How It Works

Du authentifizierst dich mit deinen eigenen Zugangsdaten und bekommst ein Bearer Token
Du fügst X-Tenant-Id: {managed-tenant-uuid} zu deinen API-Anfragen hinzu
Die API prüft, ob du den Ziel-Mandanten verwaltest
Datenisolierung wird auf Infrastrukturebene für den Ziel-Mandanten erzwungen
Alle zurückgegebenen (und erstellten) Daten gehören zum Ziel-Mandanten

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Reseller   │────>│  Mandanten-      │────>│  Isolierte   │
│   Anfrage    │     │  Kontext-        │     │  Daten       │
│              │     │  Middleware      │     │              │
│ Auth: Bearer │     │ 1. Token prüfen  │     │ Beschränkt   │
│ X-Tenant-Id  │     │ 2. Zugriff       │     │ auf Ziel-    │
│              │     │    prüfen        │     │ Team         │
└─────────────┘     └──────────────────┘     └─────────────┘

Who Can Impersonate

Rolle	Verhalten
Super-Admin	Kann `X-Tenant-Id` auf jeden beliebigen Mandanten setzen
Reseller	Kann `X-Tenant-Id` nur auf Mandanten aus der eigenen `managed_tenants`-Liste setzen
Admin / Mitglied	`X-Tenant-Id` Header wird stillschweigend ignoriert -- Anfragen verwenden immer den eigenen Mandanten

Request Examples

List Monitors in a Managed Team

bash

curl https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000"

Create a Monitor in a Managed Team

bash

curl -X POST https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunden-Webseite",
    "url": "https://customer.com",
    "type": "uptime",
    "interval": 60,
    "is_enabled": true
  }'

View Incidents in a Managed Team

bash

curl https://app.hoppla.dev/api/v1/incidents \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: 550e8400-e29b-41d4-a716-446655440000"

Finding the Tenant ID

Die tenant_id jedes verwalteten Teams bekommst du an mehreren Stellen:

POST /auth/token-Antwort (im managed_teams-Array)
GET /reseller/managed-teams-Antwort (das Feld tenant_id bei jedem Team)
POST /reseller/managed-teams-Antwort (beim Anlegen eines neuen Teams)

Dashboard: "View as This Team"

Im Dashboard funktioniert die Impersonation über die Team-Auswahl:

Geh zu Teams in der Seitenleiste
Klick bei einem verwalteten Team auf Als dieses Team anzeigen
Das Dashboard wechselt den Kontext -- alle Seiten zeigen jetzt die Daten des Teams
Klick auf das Team-Auswahlmenü und wähl Zurück zu meinem Konto, um zurückzukehren

Security Model

Zugehörigkeit wird bei jeder Anfrage geprüft: Jede API-Anfrage verifiziert, dass du den Ziel-Mandanten verwaltest. Es gibt kein Caching -- die Prüfung erfolgt live.
Isolierung auf Infrastrukturebene: Datenisolierung wird auf Infrastrukturebene erzwungen, nicht nur im Anwendungscode. Selbst bei Anwendungsfehlern ist mandantenübergreifender Datenzugriff ausgeschlossen.
Auditprotokoll: Alle Aktionen während der Impersonation werden der Benutzer-ID des Resellers zugeordnet, nicht den Benutzern des verwalteten Teams.
Keine Rechteausweitung: Impersonation gibt dir keinen Super-Admin-Zugang. Du kannst Standard-API-Operationen ausführen (Monitore erstellen/bearbeiten/löschen, Vorfälle anzeigen usw.), aber keine Mandanten-Einstellungen oder Benutzerrollen innerhalb des verwalteten Teams ändern.

Error Responses

Status	Szenario
403	`X-Tenant-Id` zeigt auf einen Mandanten, den du nicht verwaltest
403	`X-Tenant-Id` ist eine gültige UUID, aber der Mandant existiert nicht
400	`X-Tenant-Id` hat kein gültiges UUID-Format

Fehlerbeispiel:

json

{
  "message": "You do not manage this tenant."
}

Caveats

Benachrichtigungsregeln und -kanäle werden nicht mandantenübergreifend geteilt. Wenn du während der Impersonation einen Benachrichtigungskanal erstellst, gehört er zum verwalteten Team.
Reseller-Webhook-Events gehen immer an die Benachrichtigungskanäle des Resellers, nicht an die des verwalteten Teams.
Rate-Limits werden pro Token gezählt, nicht pro Mandantenkontext. Die Impersonation mehrerer Teams erhöht dein Rate-Limit-Kontingent nicht.
Branding ist mandantenspezifisch. Verwende GET/PATCH /reseller/branding mit X-Tenant-Id, um das Branding eines verwalteten Teams zu verwalten. Die SMTP-Konfiguration (/smtp-config) ist genauso auf den impersonierten Mandanten beschränkt.

Method 2: Impersonation Tokens

Für automatisierte Workflows (CI/CD, Provisionierungs-Skripte) kannst du kurzlebige Tokens erstellen, die bereits auf den Mandanten eines verwalteten Teams beschränkt sind. Diese Tokens funktionieren wie normale Bearer Tokens, ohne dass der X-Tenant-Id Header nötig ist.

How It Works

Du rufst POST /reseller/managed-teams/{id}/impersonation-tokens mit einer TTL auf (1–15 Minuten; Standard und Maximum 15)
Die API erstellt einen Service-Benutzer im Ziel-Mandanten (falls noch keiner existiert)
Für diesen Service-Benutzer wird ein Token mit den Scopes read + write erstellt
Du verwendest das zurückgegebene plain_text_token als normales Bearer Token
Das Token operiert automatisch im Mandanten-Kontext des verwalteten Teams
Das Token läuft nach der angegebenen TTL ab

┌─────────────┐     ┌────────────────┐     ┌─────────────┐
│   Reseller   │────>│   Create       │────>│  Service     │
│   Account    │     │   Impersonation│     │  User Token  │
│              │     │   Token        │     │  (in target  │
│ POST /reseller│    │                │     │   tenant)    │
│ /managed-teams│    │ 1. Find team   │     │              │
│ /{id}/imperf- │    │ 2. Create svc  │     │ Expires in   │
│ sonation-tokens│   │    user        │     │ N minutes    │
└──────────────┘    │ 3. Issue token │     └──────────────┘
                    │ 4. Audit log   │
                    └────────────────┘

Create an Impersonation Token

bash

curl -X POST https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../impersonation-tokens \
  -H "Authorization: Bearer $RESELLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl_minutes": 10}'

Antwort:

json

{
  "data": {
    "id": "token-uuid-...",
    "managed_team_id": "mt-uuid-...",
    "managed_tenant_id": "tenant-uuid-...",
    "scopes": ["read", "write"],
    "expires_at": "2026-03-10T14:10:00.000000Z",
    "ttl_minutes": 10
  },
  "plain_text_token": "ik-9xKsecretImpersonationToken..."
}

Use the Impersonation Token

Kein X-Tenant-Id Header nötig -- das Token ist bereits beschränkt:

bash

# List monitors in the managed team
curl https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer ik-9xKsecretImpersonationToken..."

# Create a monitor in the managed team
curl -X POST https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer ik-9xKsecretImpersonationToken..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunden-Webseite",
    "url": "https://customer.com",
    "type": "uptime",
    "interval": 60,
    "is_enabled": true
  }'

List Active Tokens

bash

curl https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../impersonation-tokens \
  -H "Authorization: Bearer $RESELLER_TOKEN"

Revoke a Token Early

bash

curl -X DELETE https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../impersonation-tokens/token-uuid-... \
  -H "Authorization: Bearer $RESELLER_TOKEN"

Limits and Security

TTL: 1–15 Minuten (Standard und Maximum 15) -- Tokens können nicht verlängert, sondern nur neu erstellt werden. Persistente Tokens sind nicht möglich.
Max. aktive Tokens: 5 pro verwaltetem Team zu jeder Zeit
Auditprotokoll: Jede Erstellung eines Impersonation-Tokens wird sowohl im Auditprotokoll des Resellers als auch des verwalteten Teams festgehalten -- mit der Benutzer-ID des Resellers und dem Ziel-Team
Automatischer Ablauf: Abgelaufene Tokens werden automatisch abgelehnt
Service-Benutzer: Im Ziel-Mandanten wird ein dedizierter Service-Benutzer für den Besitz des Tokens erstellt

Generiere One-Click-Login-URLs, die Benutzer verwalteter Teams direkt im Hoppla-Dashboard authentifizieren. Das ist der einfachste Weg, um deinen Kunden Single Sign-On bereitzustellen.

How It Works

Du rufst POST /reseller/managed-teams/{id}/sso-link mit der E-Mail-Adresse des Ziel-Benutzers auf
Die API erzeugt ein signiertes JWT (HS256) und gibt eine vollständige Login-URL zurück
Der Benutzer klickt auf den Link und wird im Dashboard authentifiziert -- kein Passwort nötig
Der Link läuft nach 5 Minuten ab und kann nur einmal verwendet werden

┌─────────────┐     ┌────────────────┐     ┌─────────────┐
│   Reseller   │────>│   Generate     │────>│  SSO URL     │
│   Platform   │     │   SSO Link     │     │              │
│              │     │                │     │ /sso/partner  │
│ POST /reseller│    │ 1. Auto-config │     │ ?token=JWT    │
│ /managed-teams│    │ 2. Sign JWT    │     │ &tenant=slug  │
│ /{id}/sso-link│   │ 3. Return URL  │     │              │
└──────────────┘    └────────────────┘     │ User clicks → │
                                            │ Authenticated │
                                            └──────────────┘

bash

curl -X POST https://app.hoppla.dev/api/v1/reseller/managed-teams/mt-uuid-.../sso-link \
  -H "Authorization: Bearer $RESELLER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "[email protected]", "user_name": "Alice"}'

Antwort:

json

{
  "data": {
    "sso_url": "https://monitoring.acme.com/sso/partner?token=eyJ...&tenant=acme-corp",
    "expires_in_seconds": 300,
    "user_email": "[email protected]",
    "user_exists": true
  }
}

Teil die sso_url mit deinem Benutzer, bett sie in dein Dashboard ein oder leite darauf weiter.

Portal-bewusste URLs: Die generierte URL nutzt automatisch die beste verfügbare Portal-Domain (Domain des verwalteten Teams > Reseller-Domain > app.hoppla.dev). Damit bleibt das Session-Cookie auf der korrekten Domain und Benutzer bleiben authentifiziert.

Auto-provisioning

Du musst Partner-SSO nicht manuell konfigurieren, bevor du Login-Links nutzt. Der Endpunkt erledigt automatisch:

Erzeugt ein gemeinsames Secret (falls noch keines existiert)
Aktiviert Partner-SSO für das verwaltete Team
Aktiviert die automatische Registrierung (neue Benutzer werden beim ersten Login angelegt)
Aktiviert die Konto-Verknüpfung (bestehende Passwort-Benutzer werden mit SSO verknüpft)

Parameters

Feld	Typ	Erforderlich	Beschreibung
`user_email`	email	ja	E-Mail des Benutzers, der eingeloggt werden soll
`user_name`	string	nein	Anzeigename (wird bei der automatischen Registrierung eines neuen Benutzers verwendet)
`redirect_to`	string	nein	Dashboard-Pfad, auf den nach dem Login weitergeleitet wird, z. B. `/dashboard/monitors`

Security

Links laufen nach 5 Minuten ab
Jeder Link kann nur einmal verwendet werden (JWT-Replay-Schutz über den jti-Claim)
Alle generierten Links werden im Auditprotokoll des verwalteten Teams festgehalten
Der zugrunde liegende Partner-SSO-Mechanismus verwendet JWT-Signierung mit HS256
Wenn hide_password_login aktiviert ist, wird der Passwort-Login serverseitig blockiert (nicht nur im UI ausgeblendet) -- API-Aufrufe an /auth/login und /auth/token werden für Benutzer dieses Mandanten abgelehnt

When to Use Which Method

Szenario	Empfohlene Methode
Interaktives Durchsuchen im Dashboard	X-Tenant-Id Header
Schnelle einmalige API-Aufrufe	X-Tenant-Id Header
CI/CD-Pipeline-Automatisierung	Impersonation-Tokens
Provisionierungs-Skripte	Impersonation-Tokens
Zugriff an einen Dienst delegieren	Impersonation-Tokens
Lang laufende Vorgänge (>15 Min.)	X-Tenant-Id Header
Endbenutzer-Login von deiner Plattform	SSO-Login-Links
Self-Service-Dashboard-Zugriff für Kunden	SSO-Login-Links
Hoppla in dein Produkt einbetten	SSO-Login-Links + Passwort-Login ausblenden

Impersonation (Team-Zugriff) ​

Method 1: X-Tenant-Id Header ​

How It Works ​

Who Can Impersonate ​

Request Examples ​

List Monitors in a Managed Team ​

Create a Monitor in a Managed Team ​

View Incidents in a Managed Team ​

Finding the Tenant ID ​

Dashboard: "View as This Team" ​

Security Model ​

Error Responses ​

Caveats ​

Method 2: Impersonation Tokens ​

How It Works ​

Create an Impersonation Token ​

Use the Impersonation Token ​

List Active Tokens ​

Revoke a Token Early ​

Limits and Security ​

Method 3: SSO Login Links ​

How It Works ​

Generate a Login Link ​

Auto-provisioning ​

Parameters ​

Security ​

When to Use Which Method ​

Impersonation (Team-Zugriff)

Method 1: X-Tenant-Id Header

How It Works

Who Can Impersonate

Request Examples

List Monitors in a Managed Team

Create a Monitor in a Managed Team

View Incidents in a Managed Team

Finding the Tenant ID

Dashboard: "View as This Team"

Security Model

Error Responses

Caveats

Method 2: Impersonation Tokens

How It Works

Create an Impersonation Token

Use the Impersonation Token

List Active Tokens

Revoke a Token Early

Limits and Security

Method 3: SSO Login Links

How It Works

Generate a Login Link

Auto-provisioning

Parameters

Security

When to Use Which Method