Developer documentation

CAIN Identity

Last reviewed 31 August 2026

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

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

See Also

• CAIN Private - Private AI agent environment with identity enforcement
• CAIN Architecture - How identity fits into the trust fabric
• Evidence Protocol - How decisions are recorded