Create Delegation

Grant a delegate (e.g. an AI agent) the ability to act on behalf of a delegator (e.g. a human user).

POST /v1/delegations

The delegation is enforced server-side at every authorization check using the intersection model — the delegate's effective permissions are the intersection of its own policies and the delegator's policies. Revoking either side immediately removes access with no propagation delay.

Request

Headers

Header	Value
Authorization	Bearer azx_...
Content-Type	application/json

Body

{
  "delegator_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delegate_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "description": "Allow agent to read documents on my behalf",
  "scope": ["document:read", "document:list"],
  "expires_at": "2026-12-31T23:59:59Z"
}

Fields

Field	Type	Required	Description
delegator_id	string (uuid)	Yes	Entity ID of the delegator — the human or service granting consent.
delegate_id	string (uuid)	Yes	Entity ID of the delegate — the AI agent or service acting on behalf of the delegator.
description	string	No	Human-readable description of why this delegation was granted.
scope	string[]	No	List of action identifiers this delegation is limited to. Omit for no scope restriction.
expires_at	string (ISO 8601)	No	Timestamp at which the delegation automatically expires. Omit for no expiry.

Response

201 Created

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "delegator_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delegate_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "description": "Allow agent to read documents on my behalf",
  "scope": ["document:read", "document:list"],
  "expires_at": "2026-12-31T23:59:59Z",
  "revoked_at": null,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-06-24T10:00:00Z"
}

Error responses

Status	Description
400	Invalid request body, missing required fields, re-delegation attempted, or delegate and delegator are the same entity
401	Missing or invalid API key
404	Delegator or delegate entity not found

Example

curl -X POST https://api.vengtoo.com/v1/delegations \
  -H "Authorization: Bearer azx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "delegator_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "delegate_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "scope": ["document:read"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'