# Support-Zugriff gewähren

`POST /v1/support-access-grants` · Berechtigung `support-access-grants:write`

Gewährt dem KeenAuth-Support zeitlich begrenzten Zugriff auf diese Umgebung, zum Beispiel während er an einem Support-Ticket arbeitet. Der Zugriff ist entweder nur lesend (`read`) oder darf zusätzlich die Konfiguration ändern (`read_write_config`); Support-Mitarbeiter schreiben niemals Daten von Endnutzern. Jede Nutzung der Freigabe und jede Aktion eines Mitarbeiters wird im Verwaltungs-Audit-Log protokolliert, und ein Ereignis `support_access_grant.created` wird veröffentlicht. Freigaben können nur im Dashboard von einem `owner` oder `admin` erstellt werden, der sich in den letzten 5 Minuten erneut angemeldet hat; API-Schlüssel und Maschinenclients erhalten `403 insufficient_permissions`.

## Anfrage

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `Idempotency-Key` | header | nein | Optional. 16-64 Zeichen `[A-Za-z0-9_-]`; die Wiederholung desselben Schlüssels mit demselben Body liefert dieselbe Freigabe. |
| `scope` | string | ja | `read` (nur lesend) oder `read_write_config` (darf zusätzlich die Konfiguration ändern). |
| `duration_hours` | integer | ja | Dauer in Stunden, 1-72. |
| `ticket_ref` | string | ja | Referenz des Support-Tickets: 1-200 druckbare ASCII-Zeichen, ohne führendes oder nachgestelltes Leerzeichen. |
| `allowed_regions_of_staff` | array \| null | nein | Nur Enterprise. Die Freigabe darf nur von Mitarbeitern in diesen Regionen (`eu`, `us`) genutzt werden; fehlt das Feld oder ist es `null`, gibt es keine Einschränkung. |

Anfrage-Body:

```json
{
  "scope": "read",
  "duration_hours": 24,
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"]
}
```

## Antwort

`201 Created` mit der neuen Freigabe.

```json
{
  "id": "sag_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "scope": "read",
  "status": "active",
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"],
  "granted_by": "du_01j9xk2p5n7q9s1t3v5w7y9z1b",
  "created_at": "2026-10-12T09:30:00.123456Z",
  "expires_at": "2026-10-13T09:30:00.123456Z",
  "revoked_at": null
}
```

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 400 | `malformed_request` | Der Body ist kein gültiges JSON oder `Idempotency-Key` ist fehlerhaft. |
| 403 | `insufficient_permissions` | Die Anfrage wurde nicht aus dem Dashboard von einem `owner` oder `admin` gestellt, oder der Anmeldeinformation fehlt die erforderliche Berechtigung. |
| 403 | `plan_feature_unavailable` | `allowed_regions_of_staff` erfordert den Enterprise-Plan. |
| 422 | `validation_failed` | Ein Feld ist ungültig (`scope`, `duration_hours` außerhalb von 1-72, `ticket_ref`, `allowed_regions_of_staff`). |
| 422 | `idempotency_key_reuse` | Der `Idempotency-Key` wurde bereits mit einem anderen Body verwendet. |
| 401 | `unauthenticated` | Die Anmeldeinformation fehlt, ist ungültig oder widerrufen. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; nach Ablauf der `Retry-After`-Zeit erneut versuchen. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; nach Ablauf der `Retry-After`-Zeit erneut versuchen. |

## Beispiel

Erstellen und Widerrufen sind Aktionen im Dashboard. Die Anfrage, die das Dashboard sendet:

```http
POST /v1/support-access-grants
Content-Type: application/json
Idempotency-Key: 2f1c9a7e-5b3d-4e8f-9a6c-1d2e3f4a5b6c

{
  "scope": "read",
  "duration_hours": 24,
  "ticket_ref": "SUP-48213",
  "allowed_regions_of_staff": ["eu"]
}
```