Skip to main content

Agent identity

Availability

Cloud & Enterprise · Enterprise plan

Agent identity gives every autonomous agent a first-class, verifiable identity — a record in a registry and one or more scoped credentials it presents to act. It turns "some code called our API" into "this named agent, owned by this team, in this environment, using this credential" — the foundation for trust policies and federation.

The agent registry​

Register each agent so it exists as a managed object rather than an anonymous key holder. A registered agent carries:

FieldMeaning
idStable identifier the agent uses everywhere (credentials, trust rules).
nameHuman-readable display name.
ownerThe team or user accountable for the agent.
environmentWhere the agent runs (for example development, production).

Registry endpoints:

  • GET /v1/identity/agents — list registered agents.
  • POST /v1/identity/agents — register an agent (id, name, owner, environment).
  • DELETE /v1/identity/agents/{agentID} — remove an agent.

Scoped credentials​

Each agent can hold one or more credentials. A credential is scoped — it grants only the capabilities listed in its scopes[] — and is designed to be short-lived and rotatable rather than a permanent secret.

Credential properties:

  • Secret shown once — the full secret is returned only at creation; copy it then, because it is never displayed again.
  • SHA-256 hashed — the server stores only a hash of the secret plus a non-secret prefix, so a leaked datastore cannot reveal live credentials.
  • scopes[] — the explicit set of capabilities the credential is allowed to use.
  • Rotate / revoke — replace or immediately invalidate a credential without deleting the agent.
  • expires — an expiry, after which the credential stops being accepted.
note

Because only a hash is stored, a lost credential cannot be recovered — rotate it to issue a new secret, or revoke it to cut off access.

Credential endpoints:

  • GET /v1/identity/agents/{agentID}/credentials — list an agent's credentials.
  • POST /v1/identity/agents/{agentID}/credentials — issue a scoped credential (returns the secret once).
  • DELETE /v1/identity/credentials/{credID} — revoke a credential.

Where identity events go​

Every identity event is written to the append-only activity ledger, so registration, credential issuance, rotation, and revocation are all part of the tamper-evident audit trail.

Next steps​

  • Trust policies — control which agents may act on behalf of which, with deny-wins evaluation.
  • Federation — let agents authenticate with tokens from your existing OIDC identity provider.
  • REST API — the full /v1 identity surface.