# API-Schlüssel und Scopes

> Wie ein up4-API-Schlüssel angelegt, gesendet und geprüft wird: der Bearer-Header, der Scope je Route, Schlüssel zum Lesen, Rotation und die Fehler, wenn etwas fehlt.

Source: https://upfour.io/de/docs/api/keys-and-scopes

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.](https://upfour.io/docs/images/api-tokens.webp)

**Create a scoped token.** Name, access level and permissions in the token form.

1. **Token name** Choose a name that identifies the integration, such as CI integration.
2. **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.
3. **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:

```bash
export UP4_API_KEY="pls_…"

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

```json
{
  "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](https://upfour.io/de/docs/api/client-scope.md).

## 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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-unauthorized) | API key required | Das Token beginnt nicht mit pls\_. |
| 401 | [unauthorized](https://upfour.io/docs/api/errors#code-unauthorized) | Invalid API key | Der Schlüssel ist unbekannt, widerrufen oder abgelaufen, oder sein Unternehmen wurde gelöscht. |
| 401 | [unauthorized](https://upfour.io/docs/api/errors#code-unauthorized) | Session cookie required | Es fehlt der Authorization-Header ganz; die Anfrage gilt dann als Browser-Anfrage. |
| 401 | [unauthorized](https://upfour.io/docs/api/errors#code-unauthorized) | Invalid organization | Wer den Schlüssel angelegt hat, gehört dem Unternehmen nicht mehr an. |
| 403 | [insufficient_scope](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-insufficient_scope) | API token cannot access this route | Die Route gehört nicht zur öffentlichen API. |
| 403 | [read_only_api_key](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/docs/api/errors#code-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](https://upfour.io/de/docs/api/responses.md); jeden Code listet der [Fehlerkatalog](https://upfour.io/docs/api/errors.md) (englisch), zum Beispiel [insufficient_scope](https://upfour.io/docs/api/errors#code-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`.