Identity Delegations

Identity delegations grant provider permissions from one identity owner to another actor, with optional per-credential overrides.

Identity Delegations object

Attributes

object

String

String representing the object's type

String

Unique delegation identifier.

status

Enum

Current status of the delegation.

denied_reason

EnumNullable

Reason the delegation was denied, if applicable.

delegation_level

Number

Depth level of this delegation in the delegation chain.

permissions

Array

Permissions granted by this delegation.

attestation

ObjectNullable

note

StringNullable

Optional note explaining the delegation.

metadata

ObjectNullable

Additional metadata associated with the delegation.

identity

Object

delegation_config_id

StringNullable

Delegation config used to evaluate this delegation.

parties

Object

Actors involved in the delegation and their roles.

request

ObjectNullable

credential_overrides

Object

Per-credential permission overrides attached to the delegation.

created_at

Date

Timestamp when the delegation was created.

expires_at

DateNullable

Timestamp when the delegation expires, if set.

revoked_at

DateNullable

Timestamp when the delegation was revoked, if revoked.

{
  "object": "identity.delegation",
  "id": "idd_7gHjKlMnPqRsTuVw",
  "status": "waiting_for_consent",
  "denied_reason": "request_denied",
  "delegation_level": 0,
  "permissions": [
    "provider:call",
    "provider:call"
  ],
  "attestation": {
    "object": "identity.delegation_attestation",
    "id": "ida_3xYzAbCdEfGhIjKl",
    "type": "api",
    "created_at": "2026-02-03T10:15:00.000Z"
  },
  "note": "Temporary support access for incident triage",
  "metadata": {},
  "identity": {
    "object": "identity#preview",
    "id": "idn_5gHjKlMnPqRsTuVw",
    "name": "Jane Doe",
    "description": "Customer support engineer",
    "metadata": {}
  },
  "delegation_config_id": "idc_2mNpQrStUvWxYzAb",
  "parties": [
    {
      "object": "identity.delegation_party",
      "id": "idp_4dEfGhJkLmNpQrSt",
      "roles": [
        "owner",
        "owner"
      ],
      "actor": {
        "object": "identity.actor",
        "id": "iac_6wQpLk2mZa8nYx4b",
        "type": "person",
        "status": "active",
        "name": "Build Bot",
        "description": "CI agent used for release automation",
        "metadata": {},
        "agent_id": "agt_4mNoPq8rSt2uVx6y",
        "created_at": "2026-02-03T10:15:00.000Z",
        "updated_at": "2026-02-10T14:30:00.000Z"
      },
      "created_at": "2026-02-03T10:15:00.000Z"
    },
    {
      "object": "identity.delegation_party",
      "id": "idp_4dEfGhJkLmNpQrSt",
      "roles": [
        "owner",
        "owner"
      ],
      "actor": {
        "object": "identity.actor",
        "id": "iac_6wQpLk2mZa8nYx4b",
        "type": "person",
        "status": "active",
        "name": "Build Bot",
        "description": "CI agent used for release automation",
        "metadata": {},
        "agent_id": "agt_4mNoPq8rSt2uVx6y",
        "created_at": "2026-02-03T10:15:00.000Z",
        "updated_at": "2026-02-10T14:30:00.000Z"
      },
      "created_at": "2026-02-03T10:15:00.000Z"
    }
  ],
  "request": {
    "object": "identity.delegation_request",
    "id": "idr_2mNpQrStUvWxYzAb",
    "status": "pending",
    "denied_reason": "request_denied",
    "requester": {
      "object": "identity.actor",
      "id": "iac_6wQpLk2mZa8nYx4b",
      "type": "person",
      "status": "active",
      "name": "Build Bot",
      "description": "CI agent used for release automation",
      "metadata": {},
      "agent_id": "agt_4mNoPq8rSt2uVx6y",
      "created_at": "2026-02-03T10:15:00.000Z",
      "updated_at": "2026-02-10T14:30:00.000Z"
    },
    "identity_id": "idn_5gHjKlMnPqRsTuVw",
    "expires_at": "2026-03-03T10:15:00.000Z",
    "created_at": "2026-02-03T10:15:00.000Z"
  },
  "credential_overrides": [
    {
      "object": "identity.delegation_credential_override",
      "id": "idco_9pQrStUvWxYzAbCd",
      "status": "active",
      "permissions": [
        "provider:call",
        "provider:call"
      ],
      "credential_id": "icr_8vBnM4xZa2cDf7gH",
      "created_at": "2026-02-03T10:15:00.000Z",
      "expires_at": "2026-03-03T10:15:00.000Z"
    },
    {
      "object": "identity.delegation_credential_override",
      "id": "idco_9pQrStUvWxYzAbCd",
      "status": "active",
      "permissions": [
        "provider:call",
        "provider:call"
      ],
      "credential_id": "icr_8vBnM4xZa2cDf7gH",
      "created_at": "2026-02-03T10:15:00.000Z",
      "expires_at": "2026-03-03T10:15:00.000Z"
    }
  ],
  "created_at": "2026-02-03T10:15:00.000Z",
  "expires_at": "2026-03-03T10:15:00.000Z",
  "revoked_at": "2026-02-12T17:45:00.000Z"
}

List identity delegations

Returns a paginated list of identity delegations for the instance.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

status

UnionOptional

Filter by one or more delegation statuses.

permissions

UnionOptional

Filter by one or more granted permissions.

UnionOptional

Filter by delegation ID or IDs.

owner_actor_id

UnionOptional

Filter by owner actor ID or IDs.

delegator_actor_id

UnionOptional

Filter by delegator actor ID or IDs.

delegatee_actor_id

UnionOptional

Filter by delegatee actor ID or IDs.

identity_id

UnionOptional

Filter by identity ID or IDs.

created_at

ObjectOptional

Filter identity delegation creation time by date range

updated_at

ObjectOptional

Filter identity delegation last update time by date range

GEThttp://api.metorial.com/identity-delegations

cURL

curl -X GET "https://api.metorial.com/identity-delegations" \
  -H "Authorization: Bearer metorial_sk_..."

Get identity delegation

Retrieves a specific identity delegation by ID.

URL Parameters

identity_delegation_id

String

The unique identifier for the identity_delegation

GEThttp://api.metorial.com/identity-delegations/:identity_delegation_id

cURL

curl -X GET "https://api.metorial.com/identity-delegations/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create identity delegation

Creates a new identity delegation.

Request Body

identity_id

String

Identity to delegate.

delegator_actor_id

StringOptional

Actor initiating the delegation, if different from the owner.

delegatee_actor_id

String

Actor receiving the delegation.

permissions

ArrayOptional

Permissions to grant as part of the delegation.

expires_at

DateOptional

Optional expiration timestamp for the delegation.

delegation_config_id

StringOptional

Delegation config to use for this delegation.

credential_overrides

ObjectOptional

Optional per-credential permission overrides.

note

StringOptional

Optional human-readable note for the delegation.

metadata

ObjectOptional

Additional metadata to store on the delegation.

POSThttp://api.metorial.com/identity-delegations

cURL

curl -X POST "https://api.metorial.com/identity-delegations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "identity_id": "example_identity_id",
  "delegator_actor_id": "example_delegator_actor_id",
  "delegatee_actor_id": "example_delegatee_actor_id",
  "permissions": [
    "provider:call"
  ],
  "expires_at": "2026-04-04T19:03:23.810Z",
  "delegation_config_id": "example_delegation_config_id",
  "credential_overrides": {
    "credential_id": "example_credential_id",
    "permissions": [
      "provider:call"
    ],
    "expires_at": "2026-04-04T19:03:23.810Z"
  },
  "note": "example_note",
  "metadata": {}
}'

Revoke identity delegation

Revokes an existing identity delegation.

URL Parameters

identity_delegation_id

String

The unique identifier for the identity_delegation

POSThttp://api.metorial.com/identity-delegations/:identity_delegation_id/revoke

cURL

curl -X POST "https://api.metorial.com/identity-delegations/ide_Rm4Mnheq2bfEPhBhP7SY/revoke" \
  -H "Authorization: Bearer metorial_sk_..."