Erste Schritte

Diese Anleitung führt dich durch deine erste Integration mit der Hoppla Reseller API.

Voraussetzungen

• Ein unterzeichneter Reseller-Vertrag (Mindestlaufzeit 12 Monate, Zahlung monatlich oder jährlich) -- siehe Preise & Vertragsbedingungen
• Ein Hoppla-Konto mit der Rolle Reseller (wird nach Vertragsabschluss aktiviert)
• Deine Zugangsdaten (E-Mail + Passwort)

Authentifizierung

Alle API-Anfragen brauchen ein Bearer Token. Du bekommst eins, indem du deine Zugangsdaten eintauschst:

curl -X POST https://app.hoppla.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "dein-passwort",
    "device_name": "Integrationsserver"
  }'

Antwort (201):

{
  "token": "ss-aB3dLookup9xKsecretValue1234...",
  "user": {
    "id": "9a1b2c3d-...",
    "name": "Reseller Account",
    "email": "[email protected]",
    "tenant_id": "tenant-uuid-...",
    "role": "admin",
    "language": "en",
    "managed_teams": []
  }
}

Das token wird nur einmal angezeigt -- bewahr es sicher auf. Den token-Wert schickst du bei allen weiteren Anfragen mit:

Authorization: Bearer ss-aB3dLookup9xKsecretValue1234...

Für Server-zu-Server-Automatisierung empfehlen wir statt eines Session-Tokens ein eigenes Reseller-Verwaltungstoken (rk-…) -- siehe API-Referenz -- Reseller API Tokens. Reseller-Verwaltungs-Endpoints brauchen ein Reseller-Token mit passendem Scope; ein allgemeines read-Token funktioniert dort nicht.

Schnellstart: API

1. Verwaltetes Team anlegen

Erstell einen neuen Mandanten (Tenant) für deinen Kunden:

curl -X POST https://app.hoppla.dev/api/v1/reseller/managed-teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "starter",
    "label": "Enterprise-Kunde #42",
    "admin_email": "[email protected]",
    "admin_name": "Jane Doe",
    "admin_password": "securepassword123"
  }'

Antwort (201):

{
  "data": {
    "id": "mt-uuid-...",
    "tenant_id": "new-tenant-uuid-...",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "starter",
    "label": "Enterprise-Kunde #42",
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-01-15T10:30:00.000000Z"
  }
}

2. Verwaltete Teams auflisten

curl https://app.hoppla.dev/api/v1/reseller/managed-teams \
  -H "Authorization: Bearer $TOKEN"

3. Team-Kontext wechseln (Impersonation)

Du kannst auf die Ressourcen eines verwalteten Teams zugreifen, indem du den X-Tenant-Id Header setzt:

curl https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: new-tenant-uuid-..."

Damit bekommst du die Monitore des verwalteten Teams -- nicht die deines eigenen Mandanten.

4. Monitor in einem verwalteten Team erstellen

curl -X POST https://app.hoppla.dev/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: new-tenant-uuid-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Webseite",
    "url": "https://acmecorp.com",
    "type": "uptime",
    "interval": 60,
    "is_enabled": true
  }'

5. Team-Zusammenfassung abrufen

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

Liefert die Anzahl der Monitore, offene Vorfälle und einen Gesundheitsüberblick für das Team.

6. Team-Nutzung abrufen

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

Liefert Nutzungsmetriken für die Abrechnung.

Schnellstart: Dashboard

1. Melde dich unter https://app.hoppla.dev mit deinen Reseller-Zugangsdaten an
2. Geh zu Teams in der Seitenleiste
3. Klick auf Team erstellen, um einen neuen Kunden anzulegen
4. Füll Teamname, Slug, Tarif und optional einen Admin-Benutzer aus
5. Klick auf Als dieses Team anzeigen, um dessen Monitore und Einstellungen zu verwalten
6. Über das Team-Auswahlmenü wechselst du zurück zu deinem eigenen Kontext

White-Label-Branding

Passe an, wie die Nutzer deiner verwalteten Teams Benachrichtigungen und E-Mails sehen:

1. Branding festlegen -- PATCH /branding mit deinem Markennamen, Alert-Präfix, Logos, Farben und Footer
2. SMTP konfigurieren (optional) -- PATCH /smtp-config, um E-Mails von deiner eigenen Domain zu versenden
3. Alle Benachrichtigungskanäle (E-Mail, Slack, Discord, Teams, Telegram, PagerDuty, Webhook) verwenden dein individuelles Branding

Details findest du unter API-Referenz -- Branding und API-Referenz -- Custom SMTP.

Nächste Schritte

• API-Referenz -- Vollständige Endpoint-Dokumentation (Teams, Branding, SMTP, Kanäle)
• Impersonation -- So funktioniert der mandantenübergreifende Zugriff
• Webhooks -- Abonniere Provisionierungs- und Monitor-Events