# Grant support access

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

Gives KeenAuth support staff time-limited access to this environment, for example while they work on a support ticket. Access is either read-only (`read`) or may also change configuration (`read_write_config`); support staff never write end-user data. Every use of the grant and every staff action is written to the management audit log, and a `support_access_grant.created` event is published. Grants can only be created from the dashboard by an `owner` or `admin` who signed in again within the last 5 minutes; API keys and machine clients receive `403 insufficient_permissions`.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Optional. 16-64 characters `[A-Za-z0-9_-]`; repeating the same key with the same body returns the same grant. |
| `scope` | string | yes | `read` (read-only) or `read_write_config` (may also change configuration). |
| `duration_hours` | integer | yes | Duration in hours, 1-72. |
| `ticket_ref` | string | yes | Support ticket reference: 1-200 printable ASCII characters, no leading or trailing space. |
| `allowed_regions_of_staff` | array \| null | no | Enterprise only. Only staff located in these regions (`eu`, `us`) may use the grant; omitted or `null` means no restriction. |

Request body:

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

## Response

`201 Created` with the new grant.

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

## Errors

| HTTP | code | When |
|---|---|---|
| 400 | `malformed_request` | The body is not valid JSON or `Idempotency-Key` is malformed. |
| 403 | `insufficient_permissions` | The request was not made from the dashboard by an `owner` or `admin`, or the credential lacks the required permission. |
| 403 | `plan_feature_unavailable` | `allowed_regions_of_staff` requires the Enterprise plan. |
| 422 | `validation_failed` | A field is invalid (`scope`, `duration_hours` outside 1-72, `ticket_ref`, `allowed_regions_of_staff`). |
| 422 | `idempotency_key_reuse` | The `Idempotency-Key` was already used with a different body. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

Create and revoke are dashboard actions. The request the dashboard sends:

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