> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Keys rotieren

> Ersetzen Sie einen JobHandy API-Key ohne Ausfallzeit und nehmen Sie die alten Zugangsdaten nach erfolgreicher Prüfung außer Betrieb.

Verwenden Sie dieses Runbook für eine geplante Rotation oder den Ersatz möglicherweise offengelegter Zugangsdaten.

## Vorbereitung

* Ermitteln Sie jede Runtime, jeden Worker, jeden geplanten Task und jede Secret-Referenz, die den alten Key verwendet.
* Dokumentieren Sie Name und Scope des alten Keys, ohne den geheimen Wert zu kopieren.
* Prüfen Sie, wer die erforderliche Portalberechtigung IT, HR oder Company-Admin besitzt.
* Wählen Sie ein Wartungsfenster, wenn der Client Secrets nicht dynamisch neu laden kann.
* Bereiten Sie einen Rollback-Pfad vor, bei dem der alte Key nur dann reaktiviert wird, wenn er weiterhin als vertrauenswürdig gilt.

## Rotationsablauf

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Admin as Administrator
    participant Portal as JobHandy-Administration
    participant Secrets as Secret Manager
    participant Runtime as Integrations-Runtime
    participant API as JobHandy API
    participant Monitor as Monitoring

    Admin->>Portal: Ersatz-Key mit erforderlichem Scope erstellen
    Portal-->>Admin: Key einmalig anzeigen
    Admin->>Secrets: Neue Secret-Version speichern
    Secrets-->>Runtime: Ersatz-Key bereitstellen
    Runtime->>API: Geschützte Read-Prüfung mit neuem Key
    API-->>Runtime: Erfolg + X-Request-ID
    Runtime->>Monitor: Bestätigen, dass alle Instanzen das neue Secret verwenden
    Admin->>Portal: Alten Key deaktivieren
    Monitor->>Monitor: Authentifizierungsfehler überwachen
    alt Rollout erfolgreich
        Admin->>Portal: Alten Key nach vereinbartem Prüfzeitraum löschen
    else Rolloutfehler und alter Key weiterhin vertrauenswürdig
        Admin->>Portal: Alten Key reaktivieren
        Runtime->>Secrets: Auf vorherige Secret-Version zurücksetzen
    end
```

## Verifizierungsanfragen

Verwenden Sie einen geschützten Read, der für den Scope des Keys gültig ist. `GET /health` reicht nicht aus, da dieser Endpoint nicht authentifiziert.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url 'https://api.jobhandy.io/v1/employees?page=1&pageSize=1' \
  --header 'X-API-Key: REPLACEMENT_API_KEY' \
  --header 'X-Request-ID: {{requestId}}'
```

## Notfallersatz

Wenn ein Key kompromittiert sein könnte:

1. Deaktivieren Sie ihn sofort.
2. Stoppen Sie bei Bedarf die betroffenen Integrationsinstanzen.
3. Prüfen Sie Request-IDs, Zeitpunkte, Tenants und Operationen in den verfügbaren Logs.
4. Erstellen Sie einen Ersatz mit dem kleinstmöglichen erforderlichen Scope.
5. Stellen Sie den Ersatz bereit und verifizieren Sie ihn.
6. Löschen Sie den alten Key, sobald Untersuchung und Rollback-Entscheidung dies erlauben.

## Abschlusscheckliste

* [ ] Jede Runtime verwendet die neue Secret-Version
* [ ] Für jeden erforderlichen Tenant-Kontext war eine geschützte Anfrage erfolgreich
* [ ] Keine neuen `INVALID_API_KEY`-Fehler werden durch veraltete Instanzen verursacht
* [ ] Der alte Key ist inaktiv
* [ ] Der alte Key wurde gelöscht, sobald kein Rollback mehr erforderlich war
* [ ] Rotationsdatum, ausführende Person, Scope und Request-IDs der Verifizierung sind dokumentiert