Identities

Identities bundle credentials under a single owner actor so provider access can be managed and delegated consistently.

Identities object

Attributes

object

String

String representing the object's type

id

String

Unique identity identifier.

status

Enum

Current lifecycle status of the identity.

name

StringNullable

Human-readable name of the identity.

description

StringNullable

Optional description of what the identity is used for.

metadata

ObjectNullable

Additional metadata associated with the identity.

owner

Object

credentials

Object

Credentials currently attached to the identity.

delegation_config_id

StringNullable

Default delegation config applied to the identity.

created_at

Date

Timestamp when the identity was created.

updated_at

Date

Timestamp when the identity was last updated.

{
  "object": "identity",
  "id": "idn_5gHjKlMnPqRsTuVw",
  "status": "active",
  "name": "Production GitHub Identity",
  "description": "Identity used by the release pipeline",
  "metadata": {},
  "owner": {
    "type": "actor",
    "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"
    }
  },
  "credentials": [
    {
      "object": "identity.credential",
      "id": "icr_8vBnM4xZa2cDf7gH",
      "status": "active",
      "identity_id": "idn_5gHjKlMnPqRsTuVw",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "deployment_id": "pdp_4dEfGhJkLmNpQrSt",
      "config_id": "pcf_7dEfGhJkLmNpQrSt",
      "auth_config_id": "pac_3nOpRsTuVwXyZaBc",
      "delegation_config_id": "idc_2mNpQrStUvWxYzAb",
      "created_at": "2026-02-03T10:15:00.000Z",
      "updated_at": "2026-02-10T14:30:00.000Z"
    },
    {
      "object": "identity.credential",
      "id": "icr_8vBnM4xZa2cDf7gH",
      "status": "active",
      "identity_id": "idn_5gHjKlMnPqRsTuVw",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "deployment_id": "pdp_4dEfGhJkLmNpQrSt",
      "config_id": "pcf_7dEfGhJkLmNpQrSt",
      "auth_config_id": "pac_3nOpRsTuVwXyZaBc",
      "delegation_config_id": "idc_2mNpQrStUvWxYzAb",
      "created_at": "2026-02-03T10:15:00.000Z",
      "updated_at": "2026-02-10T14:30:00.000Z"
    }
  ],
  "delegation_config_id": "idc_2mNpQrStUvWxYzAb",
  "created_at": "2026-02-03T10:15:00.000Z",
  "updated_at": "2026-02-10T14:30:00.000Z"
}

List identities

Returns a paginated list of identities for the instance.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

search

StringOptional

Filter identities by name or description.

status

UnionOptional

Filter by one or more identity statuses.

id

UnionOptional

Filter by identity ID or IDs.

agent_id

UnionOptional

Filter by owner agent ID or IDs.

actor_id

UnionOptional

Filter by owner identity actor ID or IDs.

created_at

ObjectOptional

Filter identity creation time by date range

updated_at

ObjectOptional

Filter identity last update time by date range

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

Get identity

Retrieves a specific identity by ID.

URL Parameters

identity_id

String

The unique identifier for the identity

GEThttp://api.metorial.com/identities/:identity_id
curl -X GET "https://api.metorial.com/identities/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create identity

Creates a new identity owned by an existing identity actor.

Request Body

actor_id

String

Identity actor that will own the new identity.

name

StringOptional

Optional display name for the identity.

description

StringOptional

Optional description of the identity.

metadata

ObjectOptional

Additional metadata to store on the identity.

credentials

ObjectOptional

Credentials to create and attach as part of identity creation.

POSThttp://api.metorial.com/identities
curl -X POST "https://api.metorial.com/identities" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "actor_id": "example_actor_id",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "credentials": {
    "deployment_id": "example_deployment_id",
    "config_id": "example_config_id",
    "auth_config_id": "example_auth_config_id",
    "delegation_config_id": "example_delegation_config_id"
  }
}'

Update identity

Updates mutable fields on an existing identity.

URL Parameters

identity_id

String

The unique identifier for the identity

Request Body

name

StringOptional

Updated display name for the identity.

description

StringOptional

Updated description for the identity.

metadata

ObjectOptional

Updated metadata for the identity.

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

Delete identity

Archives an identity.

URL Parameters

identity_id

String

The unique identifier for the identity

DELETEhttp://api.metorial.com/identities/:identity_id
curl -X DELETE "https://api.metorial.com/identities/ide_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."