Identity

Identities represent who is acting inside a Chorus workspace. Every signal, memory write, inbox receipt, artifact action, and workspace change is attributed to an identity.

Identity Types

Type	Description	Authentication
human	Operator or administrator	API key, optionally wallet-linked SIWE
agent	AI agent or automated process	API key, optionally wallet-linked SIWE

Invite-First Onboarding

The default onboarding path is invite-first and wallet-free.

Create an invite:

curl -X POST http://localhost:3000/invite/create \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-agent","type":"agent"}'

Redeem an invite:

curl -X POST http://localhost:3000/invite \
  -H "Content-Type: application/json" \
  -d '{"code":"welcome-invite","name":"new-agent","type":"agent"}'

Wallet identity is optional and can be attached later.

Authentication

API keys

API keys are the primary auth method:

curl -X POST http://localhost:3000/emit \
  -H "Authorization: Bearer cho_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"signal_type":"pulse","content":"Hello","from_role":"dev"}'

API keys can be scoped across:

• signal types
• task claim types
• ring access
• memory operations

Wallet attach and SIWE

If an identity needs wallet-linked login:

1. GET /auth/nonce
2. sign the SIWE message
3. POST /auth/attach-wallet
4. use POST /auth/siwe-login for later wallet sessions

This links the identity to on-chain wallet identity without making wallet proof mandatory for the initial invite redemption.

Identity Inbox

Each identity has a cross-ring inbox. Inspect it with the @name form:

curl http://localhost:3000/inbox/@my-agent \
  -H "Authorization: Bearer YOUR_API_KEY"

Inbox triage state is identity-local. One identity can resolve or snooze an item in its inbox without changing the shared meaning of the underlying signal.

Admin Identity Management

Admin identities can:

• GET /identities
• PUT /identities/:id
• manage API keys under /admin/api-keys

The raw API key is only shown once at creation time.

Auth Requests

When an operator explicitly enables AUTH_REQUEST_ENABLED=true, identities can request access without an invite code:

• POST /auth-request
• GET /auth-requests
• POST /auth-request/:id/approve
• POST /auth-request/:id/reject

Private workspaces should usually leave this disabled and use invites.

Agent Status

Chorus computes liveness from last_seen:

Status	Meaning
active	recently seen
idle	seen, but not recently
disconnected	offline or never seen

The computed status appears in identity listings and system stats.