# Accorder un accès au support

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

Accorde à l'équipe support de KeenAuth un accès limité dans le temps à cet environnement, par exemple pendant qu'elle traite un ticket de support. L'accès est soit en lecture seule (`read`), soit peut aussi modifier la configuration (`read_write_config`) ; le personnel du support n'écrit jamais de données d'utilisateurs finaux. Chaque utilisation de l'autorisation et chaque action du personnel est écrite dans le journal d'audit de gestion, et un événement `support_access_grant.created` est publié. Les autorisations ne peuvent être créées que depuis le tableau de bord, par un `owner` ou un `admin` qui s'est de nouveau connecté au cours des 5 dernières minutes ; les clés API et les clients machine reçoivent `403 insufficient_permissions`.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `Idempotency-Key` | header | non | Facultatif. 16-64 caractères `[A-Za-z0-9_-]` ; répéter la même clé avec le même corps renvoie la même autorisation. |
| `scope` | string | oui | `read` (lecture seule) ou `read_write_config` (peut aussi modifier la configuration). |
| `duration_hours` | integer | oui | Durée en heures, 1-72. |
| `ticket_ref` | string | oui | Référence du ticket de support : 1-200 caractères ASCII imprimables, sans espace en début ni en fin. |
| `allowed_regions_of_staff` | array \| null | non | Enterprise uniquement. Seul le personnel situé dans ces régions (`eu`, `us`) peut utiliser l'autorisation ; omis ou `null` signifie aucune restriction. |

Corps de la requête :

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

## Réponse

`201 Created` avec la nouvelle autorisation.

```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
}
```

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 400 | `malformed_request` | Le corps n'est pas un JSON valide ou `Idempotency-Key` est mal formé. |
| 403 | `insufficient_permissions` | La requête n'a pas été faite depuis le tableau de bord par un `owner` ou un `admin`, ou l'identifiant n'a pas la permission requise. |
| 403 | `plan_feature_unavailable` | `allowed_regions_of_staff` nécessite le plan Enterprise. |
| 422 | `validation_failed` | Un champ est invalide (`scope`, `duration_hours` hors de 1-72, `ticket_ref`, `allowed_regions_of_staff`). |
| 422 | `idempotency_key_reuse` | L'`Idempotency-Key` a déjà été utilisée avec un autre corps. |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après le délai `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après le délai `Retry-After`. |

## Exemple

Création et révocation sont des actions du tableau de bord. Requête envoyée par le tableau de bord :

```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"]
}
```