Skip to main content
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:[email protected] 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 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.
Belongs to a workspace · Named by many agents (N:1, immutable) · Owns connections · Materialized lazily, so there is no create endpoint

​
Rules

  • Identity is chosen once and never changes. See 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.