---
title: "Delegation API"
description: "Grant, narrow, inspect and revoke delegated authority."
label: "Delegation"
generated: "the API catalogue in apps/control-plane/src/routes/developer.ts"
---


The one invariant that matters: a child delegation can never exceed its parent. Attempts to widen scope, raise a ceiling or extend an expiry past the parent are refused with `DELEGATION_ESCALATION`, and revocation cascades to everything derived from the revoked grant.

## Endpoints

| | Endpoint | Permission | Notes |
| --- | --- | --- | --- |
| `GET` | `/v1/delegations` | `delegation:read` | — |
| `POST` | `/v1/delegations` | `delegation:create` | accepts `Idempotency-Key` |
| `POST` | `/v1/delegations/simulate` | `delegation:simulate` | — |
| `GET` | `/v1/delegations/graph` | `delegation:read` | — |
| `PATCH` | `/v1/delegations/{delegationId}` | `delegation:update` | — |
| `POST` | `/v1/delegations/{delegationId}/revoke` | `delegation:revoke` | — |

## What each endpoint does

### `GET /v1/delegations`

List delegations.

Requires `delegation:read`.

### `POST /v1/delegations`

Create a delegation. A child can never exceed its parent.

Requires `delegation:create`.

### `POST /v1/delegations/simulate`

Check whether a delegation would be permitted.

Requires `delegation:simulate`.

### `GET /v1/delegations/graph`

Delegation graph nodes and edges.

Requires `delegation:read`.

### `PATCH /v1/delegations/{delegationId}`

Reduce a delegation. Widening is refused.

Requires `delegation:update`.

### `POST /v1/delegations/{delegationId}/revoke`

Revoke, cascading to derived delegations.

Requires `delegation:revoke`.

Request body:

```json
{
  "reason": "string"
}
```