API-Tokens

Mit API-Tokens authentifizierst du dich gegenüber der Hoppla-API -- perfekt für Automatisierung und Integrationen. Tokens sind an dein Team gebunden und lassen sich über fein abgestufte Scopes auf bestimmte Berechtigungen einschränken.

Token erstellen

1. Gehe zu Einstellungen > API-Tokens.
2. Klicke auf Token erstellen.
3. Gib dem Token einen aussagekräftigen Namen (z. B. "CI/CD Pipeline", "Monitoring-Dashboard").
4. Wähle die Scopes (Berechtigungen) aus, die das Token braucht.
5. Lege optional ein Ablaufdatum fest.
6. Klicke auf Erstellen.
7. Kopiere das Token sofort.

WARNING

Das Token wird nur einmal angezeigt -- direkt bei der Erstellung. Wenn du es verlierst, musst du ein neues erstellen.

So sieht ein Token aus

Ein Hoppla-API-Token ist ein undurchsichtiger Schlüssel, der mit sk- beginnt und rund 55 Zeichen lang ist, zum Beispiel:

sk-a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVwXyZ...

Das vollständige Token siehst du einmal, direkt nach dem Erstellen. Danach zeigt die Token-Liste nur noch einen maskierten Ausschnitt wie sk-...aB3d -- so kannst du deine Tokens auseinanderhalten, der geheime Teil wird aber nie wieder angezeigt.

Token-Scopes

Tokens nutzen fein abgestufte Scopes, gegliedert nach Ressourcen-Domäne. Jede Domäne unterstützt drei Zugriffsstufen:

Stufe	Beschreibung
:read	Nur-Lese-Zugriff auf die Ressource
:write	Erstellen, Aktualisieren und Löschen
:manage	Voller Zugriff (umfasst sowohl :read als auch :write)

Verfügbare Scope-Domänen

Domäne	Lesen	Schreiben	Umfasst
monitors	Monitore auflisten, Statistiken, Uptime, Performance	Monitore erstellen, aktualisieren, löschen	CRUD + Statistiken aller Check-Typen
checks	Ergebnisse, Zeitreihen, Crawl-Läufe ansehen	Checks aktualisieren, aktivieren, deaktivieren, snoozen, auslösen	Check-Lifecycle-Management
incidents	Vorfälle auflisten und ansehen	Vorfälle erstellen, aktualisieren, bestätigen, snoozen, löschen	Vorfall-Lifecycle
notifications	Kanäle, Regeln, Logs auflisten	Kanäle/Regeln erstellen/aktualisieren, Tests senden	Alarmierungs-Konfiguration
escalation	Richtlinien und Bereitschaftspläne ansehen	Richtlinien, Pläne, Rotationen erstellen/aktualisieren	Bereitschafts-Verwaltung
status-pages	Statusseiten und Abonnenten ansehen	Seiten erstellen/aktualisieren, Domains verwalten	Öffentliche Statusseiten
maintenance	Wartungsfenster ansehen	Wartungsfenster erstellen/aktualisieren	Geplante Ausfallzeiten
team	Mitglieder und Einladungen ansehen	Einladen, Rollen ändern, Mitglieder entfernen	Team-Verwaltung
settings	Branding, SMTP, SSO, Audit-Log ansehen	Branding, SMTP, SSO, Berichte aktualisieren	Konto-Konfiguration
billing	Pläne, Transaktionen, Rechnungen ansehen	Pläne wechseln, Abos verwalten	Abrechnungs-Verwaltung

Beispiel: CI/CD-Token

Eine Deployment-Pipeline, die nur Monitore verwalten muss:

Scopes: monitors:manage, checks:write

Beispiel: Nur-Lese-Dashboard

Ein internes Dashboard, das Monitoring-Daten anzeigt:

Scopes: monitors:read, incidents:read, checks:read

Beispiel: Voller Zugriff

Ein Verwaltungstool, das vollen API-Zugriff braucht:

Scopes: monitors:manage, checks:manage, incidents:manage, notifications:manage,
        escalation:manage, status-pages:manage, maintenance:manage, team:manage,
        settings:manage, billing:manage

Schutz vor Scope-Eskalation

Wenn du ein neues Token mit einem bestehenden API-Token erstellst, müssen die Scopes des neuen Tokens eine Teilmenge der Scopes des erstellenden Tokens sein. Ein Token mit monitors:read kann kein Token mit monitors:write erstellen.

Alte Scopes

Ältere Tokens nutzen vielleicht noch die einfacheren Scopes read und read, write statt der fein abgestuften resource:action-Scopes von oben. Die werden weiterhin akzeptiert -- bestehende Integrationen laufen also einfach weiter.

Plan-Einschränkungen

Im Free-Plan (und bei Demo-Konten) sind API-Tokens auf :read-Scopes beschränkt. Um Tokens mit Schreibzugriff zu erstellen, brauchst du mindestens den Hobby-Plan oder höher.

Verfügbare Scopes auflisten

Über die API rufst du alle verfügbaren Scopes samt Beschreibungen ab:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.hoppla.dev/api/v1/api-tokens/scopes

Tokens für mehrere Teams

Wenn dein Konto (dieselbe E-Mail-Adresse) zu mehreren Teams gehört, kann ein einzelner Token auf mehrere davon gleichzeitig zugreifen — praktisch für team­übergreifende Automatisierung oder KI-Assistenten. Standardmäßig kann ein Token auf alle deine Teams zugreifen; du schließt gezielt die aus, die er nicht erreichen soll. Dein aktuelles Team ist immer enthalten. (Gehörst du nur zu einem Team, deckt ein Token einfach dieses Team ab — nichts zu konfigurieren.)

Im Dashboard: Wenn du zu mehr als einem Team gehörst, zeigt der Dialog API-Token erstellen einen Abschnitt Teams mit allen Teams bereits vorausgewählt. Entferne den Haken bei jedem Team, das du ausschließen möchtest.

Über die API:

• tenant_ids weglassen → der Token umfasst alle Teams, auf die du zugreifen kannst (Standard).
• Ein tenant_ids-Array senden, um ihn auf genau diese Teams zu beschränken (die nicht ausgeschlossene Menge):

curl -X POST https://app.hoppla.dev/api/v1/api-tokens \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nur zwei Teams",
    "scopes": ["monitors:read", "incidents:read"],
    "tenant_ids": ["<team-id-a>", "<team-id-b>"]
  }'

• Du kannst nur Teams angeben, zu denen deine Identität tatsächlich gehört — unbekannte oder nicht erlaubte IDs werden ignoriert, und dein eigenes Team bleibt immer enthalten.
• Um einen Token nur auf dein aktuelles Team zu beschränken, sende "tenant_ids": [].
• Erreicht ein Token mehrere Teams, liefern Listen-Endpunkte Daten über alle Teams hinweg, jeweils pro Team gekennzeichnet. Die Token-Liste zeigt die Team-Reichweite eines Tokens.

Die Team-Mitgliedschaft wird live geprüft: Wird dir der Zugriff auf ein Team später entzogen, erreicht der Token es sofort nicht mehr.

Token verwenden

Pack das Token in den Authorization-Header deiner API-Requests:

Authorization: Bearer YOUR_TOKEN

Beispiel mit curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.hoppla.dev/api/v1/monitors

Beispiel mit JavaScript:

const response = await fetch('https://app.hoppla.dev/api/v1/monitors', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

Token bearbeiten

Du kannst Name, Berechtigungen, Ablaufdatum und Team-Zugriff eines bestehenden Tokens jederzeit ändern — der Token-Wert bleibt gleich, deine Integrationen funktionieren also weiter.

Im Dashboard: Klicke auf das Bearbeiten-Symbol (Stift) bei einem Token, passe die Felder an und wähle Änderungen speichern.

Über die API: Sende ein PATCH mit nur den Feldern, die du ändern möchtest:

curl -X PATCH https://app.hoppla.dev/api/v1/api-tokens/<token-id> \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["monitors:read", "incidents:read"] }'

• Nur die mitgesendeten Felder werden geändert; alles, was du weglässt, bleibt unverändert.
• Es gelten dieselben Grenzen wie beim Erstellen: dein Plan, deine Rolle und — wenn du über einen API-Token bearbeitest — dessen eigene Berechtigungen. Ein Token kann nie so bearbeitet werden, dass er diese überschreitet.
• Das Bearbeiten ändert nie das Geheimnis. Um das Geheimnis zu rotieren, lösche den Token und erstelle einen neuen.

Token widerrufen

1. Gehe zu Einstellungen > API-Tokens.
2. Suche das Token, das du widerrufen willst.
3. Klicke auf Löschen.

Das wirkt sofort. Alle Anfragen mit dem gelöschten Token bekommen ab dann eine 401 Unauthorized-Antwort.

Sicherheits-Best-Practices

• Nutze nur die nötigsten Scopes. Vergib nur die Berechtigungen, die deine Integration wirklich braucht.
• Keine Tokens in die Versionskontrolle committen. Nutze stattdessen Umgebungsvariablen oder einen Secrets-Manager.
• Pro Integration ein eigenes Token. So kannst du den Zugriff einer einzelnen Integration widerrufen, ohne die anderen zu stören.
• Ablaufdaten festlegen. Tokens lassen sich so einstellen, dass sie nach 30, 60, 90 Tagen oder einem Jahr ablaufen.
• Tokens regelmäßig rotieren. Erstelle ein neues Token, aktualisiere deine Integrationen und lösche dann das alte.
• API-Nutzung im Blick behalten. Wenn du vermutest, dass ein Token kompromittiert wurde, widerrufe es sofort und erstelle ein neues.