Entwickler/Grundlagen

Ein Schlüssel, nur mit deinen Rechten.

Ein API-Schlüssel ist ein Bearer-Token und handelt als die Person, die ihn angelegt hat. Jeder Schlüssel trägt Scopes, und jede Route nennt den einen Scope, den sie braucht. Schlüssel entstehen in der App, nie über die API selbst.

Schlüssel anlegen

In der App unter Einstellungen → API-Tokens. Das Formular fragt nach einem Namen, der Zugriffsstufe (nur lesen oder lesen und schreiben), der Laufzeit (unbegrenzt, 30, 90 oder 365 Tage; vorbelegt sind 90), den Scopes und, wenn der Agenturmodus an ist, den Kunden, die der Schlüssel sehen darf.

API token form with the name CI integration, access level Read-only, and monitor.read and monitor.write checked. — **Create a scoped token.** Name, access level and permissions in the token form. Screenshot · Beispieldaten

Bildhilfe · Settings / API tokens

**Token name**Choose a name that identifies the integration, such as CI integration.
**Access level**The default for a token without explicit scopes. Read-only is the safe start. The screenshot shows the form before a token is created.
**Scopes**Select only the operations the integration needs. The example allows reading and writing monitors.

Der Schlüssel wird nur einmal angezeigt. up4 speichert nur einen SHA-256-Hash; einen verlorenen Schlüssel kann up4 nicht wieder anzeigen. Lege einen neuen an.
Jeder Schlüssel beginnt mit pls_.
Ohne ausdrückliche Scope-Liste bekommt ein Schlüssel zum Lesen alle .read-Scopes, einer zum Lesen und Schreiben alle Lese-, Schreib- und Lösch-Scopes.
Ein Schlüssel kann keine Schlüssel anlegen, rotieren oder widerrufen. Diese Routen beantwortet nur eine angemeldete Browser-Sitzung.
Rotieren in der App stellt einen neuen Schlüssel mit gleichem Namen, gleichen Scopes, gleicher Zugriffsstufe, gleichen Kunden und gleicher Laufzeit aus. Der alte läuft höchstens noch 24 Stunden weiter, du kannst also ohne Unterbrechung umstellen.
up4 merkt sich, wann ein Schlüssel zuletzt benutzt wurde.

Schlüssel senden

Setze ihn als Bearer-Token in den Authorization-Header. GET /me braucht nur self.read und zeigt, was der Schlüssel darf:

export UP4_API_KEY="pls_…"

curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY"

{
  "data": {
    "api_key_id": "…",
    "api_version": "2026-05-07",
    "auth_method": "api_key",
    "client_set": { "All": true, "CompanyLevel": true, "IDs": null },
    "org_id": "…",
    "org_role": "owner",
    "scopes": ["self.read", "monitor.read", "monitor.write", …],
    "user_id": "…"
  }
}

scopes kommt ohne feste Reihenfolge. Ein Team-Schlüssel zeigt zusätzlich team_id. client_set erklärt die Seite Kunden-Scope.

Scopes

Ein Scope heißt <Ressource>.read, .write oder, bei Monitoren, .delete. Die Referenzseiten nennen den Scope je Operation; die Tabelle zeigt, was die Gruppen abdecken.

Lese-Scope	Schreib-Scopes	Umfasst
`monitor.read`	`monitor.write, monitor.delete`	Monitore und ihre Gruppen. Write umfasst Anlegen, Ändern, Pausieren, Fortsetzen, sofort prüfen sowie Sammel- und Batch-Änderungen; Löschen ist ein eigener Scope.
`heartbeat.read`	`heartbeat.write`	Geplante Aufgaben (Heartbeats) und ihre Gruppen. Löschen braucht write.
`incident.read`	`incident.write`	Vorfälle, Schweregrade und Schweregrad-Gruppen.
`status_page.read`	`status_page.write`	Statusseiten, Vorlagen für Meldungen und Design-Vorlagen. Für Änderungen an Abonnenten braucht es status_page.subscriber.write.
`notification_channel.read`	`notification_channel.write`	Benachrichtigungskanäle.
`escalation_policy.read`	`escalation_policy.write`	Alarmpläne.
`oncall.read`	`oncall.write`	Bereitschaftspläne, Rotationen und Vertretungen.
`runbook.read`	`runbook.write`	Anleitungen (Playbooks, API-Name runbook).
`client.read`	`client.write`	Kunden und Kundenvorlagen.
`team.read`	`team.write`	Teams.
`member.read`	`member.write`	Mitglieder des Unternehmens, Einladungen und die Mitglieder eines Teams.
`report.read`	`report.write`	Berichte, Berichtspläne und Freigabelinks, SLA-Richtlinien und der Advisor.
`webhook.read`	`webhook.write`	Webhook-Abonnements und ihre Zustellungen.
`metadata.read`	`metadata.write`	Metadaten an Monitoren, Geplanten Aufgaben, Vorfällen und Kunden.
`organization.read`	`organization.write`	Einstellungen des Unternehmens: Branding, Sicherheit, SSO.
`audit_log.read`	`—`	Das Audit-Log.
`self.read`	`—`	GET /me: der Schlüssel fragt nach sich selbst.

An einem Schlüssel siehst du eventuell auch api_key.read und api_key.write. Keine öffentliche Route braucht sie.

Ein Schlüssel mit der Zugriffsstufe „nur lesen“ wird an jeder Schreib-Route abgewiesen, auch wenn seine Scope-Liste einen Schreib-Scope enthält. Zusätzlich zählt die Rolle der Person, die den Schlüssel angelegt hat: Ein Betrachter kann auch mit einem Schlüssel zum Lesen und Schreiben nichts ändern.

Wenn der Schlüssel abgewiesen wird

Status	error.code	error.message	Bedeutung
401	`unauthorized`	Invalid authorization header format	Der Header ist da, hat aber nicht die Form Bearer und Token. Das Schema unterscheidet Groß- und Kleinschreibung: Schreib Bearer.
401	`unauthorized`	API key required	Das Token beginnt nicht mit pls_.
401	`unauthorized`	Invalid API key	Der Schlüssel ist unbekannt, widerrufen oder abgelaufen, oder sein Unternehmen wurde gelöscht.
401	`unauthorized`	Session cookie required	Es fehlt der Authorization-Header ganz; die Anfrage gilt dann als Browser-Anfrage.
401	`unauthorized`	Invalid organization	Wer den Schlüssel angelegt hat, gehört dem Unternehmen nicht mehr an.
403	`insufficient_scope`	API token does not have the required scope	Dem Schlüssel fehlt der Scope, den die Route braucht. details.required_scope nennt ihn.
403	`insufficient_scope`	API token cannot access this route	Die Route gehört nicht zur öffentlichen API.
403	`read_only_api_key`	Read-only API keys cannot use write permissions	Der Schlüssel hat die Zugriffsstufe „nur lesen“, die Route braucht einen .write- oder .delete-Scope.
403	`api_key_scopes_required`	Legacy API key has no explicit scopes and must be rotated	Ein alter Schlüssel ohne Scope-Liste. Erneuere ihn in der App.
403	`session_required`	This route is available only to an authenticated browser session	Die Route gehört zur App: Schlüsselverwaltung, Abrechnung, Benutzereinstellungen, Dashboard.

Den Aufbau dieser Antworten beschreibt Antworten und Fehler; jeden Code listet der Fehlerkatalog (englisch), zum Beispiel insufficient_scope.

Routen auf Unternehmensebene wie /organization antworten mit 404 Not found, wenn der Schlüssel ein Team-Schlüssel ist oder keine Ressourcen auf Unternehmensebene lesen darf.

Typische Fehler

bearer klein schreiben oder das Wort weglassen. Beides ergibt 401.
Ein 403 für einen falschen Schlüssel halten. Ein falscher Schlüssel ist 401; 403 heißt: Der Schlüssel gilt, aber ihm fehlt der Scope oder das Schreibrecht.
Einen Schlüssel zum Lesen anlegen und später Schreibrechte erwarten. Lege einen Schlüssel zum Lesen und Schreiben an oder rotiere zu einem.
Schlüssel in Chats oder im Code ablegen. Widerrufe einen verratenen Schlüssel in der App; er gilt sofort nicht mehr.
Für eine Integration einen Schlüssel nehmen, der an eine Person gebunden ist. Verlässt diese Person das Unternehmen, antwortet der Schlüssel mit 401.

War diese Seite hilfreich?