Identity Delegation Requests

Identity delegation requests represent approval workflows for creating delegations that require consent.

Identity Delegation Requests object

Attributes

object

String

String representing the object's type

id

String

Unique delegation request identifier.

status

Enum

Current status of the delegation request.

denied_reason

EnumNullable

Reason the request ultimately resulted in a denied delegation.

requester

Object

identity_id

String

Identity targeted by the delegation request.

delegation

Object

expires_at

Date

Timestamp when the delegation request expires.

created_at

Date

Timestamp when the delegation request was created.

{
  "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",
  "delegation": {
    "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"
  },
  "expires_at": "2026-03-03T10:15:00.000Z",
  "created_at": "2026-02-03T10:15:00.000Z"
}

List identity delegation requests

Returns a paginated list of identity delegation requests.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

status

UnionOptional

Filter by one or more delegation request statuses.

id

UnionOptional

Filter by delegation request ID or IDs.

actor_id

UnionOptional

Filter by requester actor ID or IDs.

identity_id

UnionOptional

Filter by identity ID or IDs.

created_at

ObjectOptional

Filter identity delegation request creation time by date range

updated_at

ObjectOptional

Filter identity delegation request last update time by date range

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

Get identity delegation request

Retrieves a specific identity delegation request by ID.

URL Parameters

identity_delegation_request_id

String

The unique identifier for the identity_delegation_request

Query Parameters

allow_deleted

BooleanOptional

Return the request even if it has been deleted.

GEThttp://api.metorial.com/identity-delegation-requests/:identity_delegation_request_id
curl -X GET "https://api.metorial.com/identity-delegation-requests/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create identity delegation request

Creates a new identity delegation request.

Request Body

identity_id

String

Identity to request delegation for.

requester_actor_id

String

Actor requesting the delegation.

delegator_actor_id

StringOptional

Actor submitting the request on behalf of the requester.

permissions

ArrayOptional

Permissions being requested.

expires_at

Date

Timestamp when the request should expire.

delegation_config_id

StringOptional

Delegation config to use for the resulting delegation.

credential_overrides

ObjectOptional

Optional per-credential permission overrides.

note

StringOptional

Optional human-readable note for the request.

metadata

ObjectOptional

Additional metadata to store on the request.

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

Approve identity delegation request

Approves an existing identity delegation request.

URL Parameters

identity_delegation_request_id

String

The unique identifier for the identity_delegation_request

Query Parameters

allow_deleted

BooleanOptional

Allow approving a request that is already deleted.

POSThttp://api.metorial.com/identity-delegation-requests/:identity_delegation_request_id/approve
curl -X POST "https://api.metorial.com/identity-delegation-requests/ide_Rm4Mnheq2bfEPhBhP7SY/approve" \
  -H "Authorization: Bearer metorial_sk_..."

Deny identity delegation request

Denies an existing identity delegation request.

URL Parameters

identity_delegation_request_id

String

The unique identifier for the identity_delegation_request

Query Parameters

allow_deleted

BooleanOptional

Allow denying a request that is already deleted.

POSThttp://api.metorial.com/identity-delegation-requests/:identity_delegation_request_id/deny
curl -X POST "https://api.metorial.com/identity-delegation-requests/ide_Rm4Mnheq2bfEPhBhP7SY/deny" \
  -H "Authorization: Bearer metorial_sk_..."