Developer documentation

CAIN Identity

Last reviewed 31 August 2026

All docs

CAIN Identity Documentation#

Status: PRODUCTION#

CAIN Identity is production-ready. Every actor that exercises authority through the Trust Fabric must have a verifiable identity.

What is CAIN Identity?#

CAIN Identity is a cryptographically verifiable identity layer for AI agents, humans, services, and delegated actors. It provides:

SPIFFE-compatible URN format for universal identity representation
Ed25519 cryptographic keys for signing and verification
Delegation chains so authority can be traced back to a principal
Revocation that blocks enforcement - revoked identities fail-closed immediately
Audit trail of every identity operation

Core proposition: Every autonomous actor that exercises authority must have a verifiable identity before that authority is exercised.

Identity Model#

Principal (Human)
    │
    └──▶ Agent (CAIN Identity)
              │
              └──▶ Delegation (delegated authority)
                        │
                        └──▶ Sub-agent / Tool / Service

Identity Kinds#

Kind	Description	Default Capabilities
`human`	Human user	`user:read`, `user:write`
`agent`	AI agent	`tool:read`, `tool:execute`, `agent:read`
`service`	Backend service	`service:read`, `service:execute`
`delegated`	Temporary delegated identity	Inherited from parent

Architecture#

┌─────────────────────────────────────────────────────────────────┐
│                     CAIN Identity                                │
├─────────────────────────────────────────────────────────────────┤
│  Identity Engine                                                 │
│  ├── Ed25519 key pair generation                                │
│  ├── Credential issuance (one-time private key)                 │
│  ├── Signature verification                                      │
│  ├── Delegation chain validation                                │
│  └── Revocation checking                                        │
│                                                                  │
│  Identity API                                                    │
│  ├── /fabric/identity/create    - Issue new identity            │
│  ├── /fabric/identity/list      - List tenant identities        │
│  ├── /fabric/identity/{id}       - Get identity details          │
│  ├── /fabric/identity/{id}/revoke - Revoke identity            │
│  ├── /fabric/identity/{id}/delegate - Delegate authority        │
│  └── /fabric/identity/health    - Health check                  │
│                                                                  │
│  Identity Stage (in Trust Decision)                             │
│  └── Verifies identity before any consequential action          │
└─────────────────────────────────────────────────────────────────┘

API Reference#

Create Identity#

curl -X POST https://cainstudio.online/fabric/identity/create \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "agent",
    "display_name": "my-agent"
  }'

Response:

{
  "identity_id": "urn:cain:identity:agent:a1b2c3d4e5f6a1b2c3d4e5f6",
  "tenant": "your-tenant-id",
  "kind": "agent",
  "display_name": "my-agent",
  "status": "active",
  "public_key": "epK5tbJBd77loF6nO9eAF9NpQ8...",
  "key_fp": "cd9fc06dd58462bacb04e8d05",
  "key_version": 1,
  "capabilities": ["tool:read", "tool:execute", "agent:read"],
  "delegation_depth": 0,
  "expires_at": "1788444702",
  "private_key_b64": "1aiO3qvaFnyavM4gyIayXaa..."
}

⚠️ The private_key_b64 is returned ONLY once. Store it securely.

List Identities#

curl https://cainstudio.online/fabric/identity/list \
  -H "X-API-Key: your-api-key"

Get Identity#

curl https://cainstudio.online/fabric/identity/urn:cain:identity:agent:a1b2c3d4e5f6a1b2c3d4e5f6 \
  -H "X-API-Key: your-api-key"

Revoke Identity#

curl -X POST https://cainstudio.online/fabric/identity/urn:cain:identity:agent:a1b2c3d4e5f6a1b2c3d4e5f6/revoke \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "agent compromised"}'

Revocation is immediate and fail-closed: a revoked identity cannot be used to make decisions.

Delegate Authority#

curl -X POST https://cainstudio.online/fabric/identity/urn:cain:identity:agent:a1b2c3d4e5f6/sub-delegate \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "delegate_kind": "agent",
    "display_name": "sub-agent",
    "capabilities": ["tool:read"]
  }'

Verify Identity#

curl -X POST https://cainstudio.online/fabric/identity/urn:cain:identity:agent:a1b2c3d4e5f6/verify \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"challenge": "sign-this"}'

Golden E2E Test#

The canonical identity lifecycle test:

# 1. Create tenant → create human → create agent
HUMAN=$(curl -s -X POST https://cainstudio.online/fabric/identity/create \
  -H "X-API-Key: $API_KEY" \
  -d '{"kind": "human", "display_name": "alice"}')

AGENT=$(curl -s -X POST https://cainstudio.online/fabric/identity/create \
  -H "X-API-Key: $API_KEY" \
  -d '{"kind": "agent", "display_name": "bob", "parent_id": "'$HUMAN_ID'"}')

# 2. Authenticate → request action
curl -X POST https://cainstudio.online/private/execute \
  -H "X-API-Key: $API_KEY" \
  -d '{"action": "tool:read", "identity_id": "'$AGENT_ID'"}'

# 3. CAIN resolves identity → ALLOW → execute → evidence
# 4. Revoke → DENY (fail-closed)
curl -X POST https://cainstudio.online/fabric/identity/$AGENT_ID/revoke \
  -H "X-API-Key: $API_KEY"

# 5. Revoked identity now denied
curl -X POST https://cainstudio.online/private/execute \
  -H "X-API-Key: $API_KEY" \
  -d '{"action": "tool:read", "identity_id": "'$AGENT_ID'"}'
# → {"result": "DENY", "reason": "identity_verification_failed: identity_not_active (revoked)"}

Integration with CAIN Enforcement#

When you call /private/execute with an identity_id, CAIN:

1. Verifies identity exists in the tenant 2. Checks status is active (not suspended or revoked) 3. Validates credential not expired 4. Builds delegation chain if acting on behalf of another 5. Checks capabilities match required action 6. Issues ALLOW or DENY with full evidence

curl -X POST https://cainstudio.online/private/execute \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "tool:execute",
    "resource": "database:production",
    "identity_id": "urn:cain:identity:agent:a1b2c3d4e5f6",
    "required_capability": "tool:execute"
  }'

Security Properties#

Property	How
Fail-closed	Unverified identity = automatic DENY
Revocation immediate	Revoked identity cannot make decisions
Delegation traced	Full chain from sub-agent to principal
Key rotation	Key history tracked, old keys invalidated
Audit trail	Every operation logged with actor, tenant, timestamp