Identity
Identity answers three questions for every protected action: who is calling, which agent may they speak for, and is that authority still current?
Records
| Path | Purpose |
|---|---|
agents/{agentId} | Owner, suspension, session epoch, current mandate, custody, mailbox summary. |
agents/{agentId}/deviceKeys | Full-agent key hashes/ciphertexts and revocation metadata. |
agents/{agentId}/scopedKeys | Narrow credentials, including inbox binding. |
agents/{agentId}/delegations | On-behalf-of issuer, subject, scopes, expiry, and revocation. |
agents/{agentId}/mandates | Sealed grant/amend/revoke versions. |
agents/{agentId}/secrets | KMS-encrypted agent secrets; list APIs expose names only. |
Credential flows
Human owner
Firebase Auth identifies the human. Callables then verify direct ownership or the minimum named
team role. The client never grants itself a role by sending ownerUid.
Agent device or scoped key
The agent calls session with its agent ID and credential. Ujex checks the credential, agent
state, current mandate, expiry/revocation, and rate limit before returning a Firebase custom
token. The SDK exchanges it for an ID token.
Protected actions validate credential state and session version again. Rotation, revocation, mandate amendment, mandate revocation, suspension, and offboarding invalidate stale sessions.
Delegation
Only a full device credential may delegate. The subject agent must have the same owner, requested scopes must be a subset of the issuer's scopes, and TTL may not exceed one hour. Revocation and expiry are checked server-side.
Mandates
Agent creation issues an initial expiring mandate. Owners can list history, grant after expiry, amend the current version with optimistic version checking, or revoke. Every change appends an evidence row and increments the session epoch.
Passport
The signed Agent Passport exposes hashed owner identity, only a provisioned mailbox, active key prefixes/scopes, active delegations, revoked counts, and the latest audit anchor. It never exposes credential plaintext. A passport is a time-bounded statement; relying parties must verify its signature and expiry.
Offboarding
deleteAgent first suspends the agent, disables it, and increments its session epoch. It then
retires the Ruzayo mailbox/claim and removes the working agent tree. The human account and global
audit evidence remain. The Settings UI uses a hold gesture because this cleanup is destructive.
See Identity callables for the caller matrix and responses.