Identity Actors

Identity actors represent people or agents that can own identities and participate in delegations.

Identity Actors object

Attributes

object

String

String representing the object's type

id

String

Unique identity actor identifier.

type

Enum

Type of actor that owns or participates in identities.

status

Enum

Current lifecycle status of the identity actor.

name

String

Human-readable name of the identity actor.

description

StringNullable

Optional description of the actor.

metadata

ObjectNullable

Additional metadata associated with the actor.

agent_id

StringNullable

Linked agent identifier when this actor represents an agent.

created_at

Date

Timestamp when the actor was created.

updated_at

Date

Timestamp when the actor was last updated.

{
  "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"
}

List identity actors

Returns a paginated list of identity actors for the instance.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

search

StringOptional

Filter actors by name or description.

status

UnionOptional

Filter by one or more actor statuses.

id

UnionOptional

Filter by identity actor ID or IDs.

agent_id

UnionOptional

Filter by linked agent ID or IDs.

consumer_id

UnionOptional

Filter by linked consumer ID or IDs.

created_at

ObjectOptional

Filter identity actor creation time by date range

updated_at

ObjectOptional

Filter identity actor last update time by date range

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

Get identity actor

Retrieves a specific identity actor by ID.

URL Parameters

identity_actor_id

String

The unique identifier for the identity_actor

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

Create identity actor

Creates a new identity actor.

Request Body

type

Enum

Whether this actor is a person or an agent.

name

String

Human-readable display name for the actor.

description

StringOptional

Optional description of the actor.

metadata

ObjectOptional

Additional metadata to store on the actor.

POSThttp://api.metorial.com/identity-actors
curl -X POST "https://api.metorial.com/identity-actors" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "type": "person",
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'

Update identity actor

Updates mutable fields on an existing identity actor.

URL Parameters

identity_actor_id

String

The unique identifier for the identity_actor

Request Body

name

StringOptional

Updated display name for the actor.

description

StringOptional

Updated description for the actor.

metadata

ObjectOptional

Updated metadata for the actor.

PATCHhttp://api.metorial.com/identity-actors/:identity_actor_id
curl -X PATCH "https://api.metorial.com/identity-actors/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'

Delete identity actor

Archives an identity actor.

URL Parameters

identity_actor_id

String

The unique identifier for the identity_actor

DELETEhttp://api.metorial.com/identity-actors/:identity_actor_id
curl -X DELETE "https://api.metorial.com/identity-actors/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."