> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities

> Who an agent acts for.

Every agent says who it acts for. That's its **identity**, a required string
you pick when you create the agent, and it can't change afterward. The first
time Matrices sees a new value it creates a workspace-level identity you can
list, audit, and disable.

The value is up to you, at most 512 bytes of UTF-8 with no control characters.
Prefixes keep values from colliding: a bare ID like `user_123` or
`email:dana@example.com` for a person, `svc:support-triage` for an agent that
acts for your product rather than a human. The `system:` prefix is reserved.

Everything about "who" hangs off the identity. [Connections](/model/connections)
can be owned by one, so if you connect Dana's Gmail once, every agent with
Dana's identity can use it and no other agent can. Disabling an identity is a
kill switch: every agent under it refuses new turns, stops getting credentials,
and stops firing schedules and subscriptions.

The reason it can't change is that threads, private memory, files, and
credential access all pile up under it, and moving it would hand one person's
history to someone else. If you got it wrong, create a new agent.

<Info>
  **Belongs to** a workspace · **Named by** many agents (N:1, immutable) ·
  **Owns** connections · **Materialized** lazily, so there is no create endpoint
</Info>

## Rules

* Identity is chosen once and never changes. See [Rules](/model/rules).
* Sharing an identity shares credential eligibility, not memory or transcripts.
* An agent that creates another agent passes on its own identity. There is no
  field to set a different one.

## API

* `GET /v1/identities`, filtered by `query` or `prefix`.
* `POST /v1/identities/disable` and `/enable`, both idempotent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.