23blocks-os/agent-identity

Agent Identity (AID) Protocol

Authenticate AI agents with auth servers using cryptographic identity documents and proof of possession. AID is self-contained — no other protocols required.

When to use this skill

Use this skill when the user or task requires:

• Initializing an agent's Ed25519 identity
• Registering an agent's identity with an auth server
• Obtaining JWT tokens for API access via token exchange
• Checking an agent's AID registration status
• Setting up agent-to-server authentication
• Configuring scoped permissions for agent API access

Quick Start

# 1. Initialize agent identity (one-time)
aid-init.sh --auto

# 2. Register with an auth server (one-time, requires admin token)
aid-register.sh --auth https://auth.23blocks.com/acme \
  --token <ADMIN_JWT> --role-id 2

# 3. Get a JWT token
TOKEN=$(aid-token.sh --auth https://auth.23blocks.com/acme --quiet)

# 4. Use it for API calls
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/resource

Installation

For Claude Code (skill)

npx skills add agentmessaging/agent-identity

Quick Install

curl -fsSL https://raw.githubusercontent.com/agentmessaging/agent-identity/main/install.sh | bash

Manual

git clone https://github.com/agentmessaging/agent-identity.git ~/agent-identity
export PATH="$HOME/agent-identity/scripts:$PATH"

Commands Reference

aid-init.sh — Initialize Agent Identity

Create an Ed25519 keypair and identity for this agent.

aid-init.sh --auto              # Auto-detect name from environment
aid-init.sh --name my-agent     # Specify agent name
aid-init.sh --name my-agent --force  # Overwrite existing

Parameters:

• --auto — Auto-detect agent name from environment
• --name, -n — Specify agent name
• --force, -f — Overwrite existing identity

aid-register.sh — Register with Auth Server

One-time registration linking the agent's Ed25519 identity to a tenant with a specific role.

aid-register.sh --auth https://auth.23blocks.com/acme \
  --token <ADMIN_JWT> --role-id 2

Parameters:

• --auth, -a — Auth server URL (required)
• --token, -t — Admin JWT for authorization (required)
• --role-id, -r — Role ID to assign (required)
• --api-key, -k — API key (X-Api-Key header)
• --name, -n — Display name (default: agent name)
• --description, -d — Agent description
• --lifetime, -l — Token lifetime in seconds (default: 3600)

What it does:

1. Reads the agent's Ed25519 public key and identity
2. POSTs the registration to the server's agent registration endpoint
3. Stores the registration locally for future token exchanges

aid-token.sh — Exchange Identity for JWT Token

Performs the OAuth 2.0 token exchange using grant_type=urn:aid:agent-identity.

# Get a token (uses cache if valid)
aid-token.sh --auth https://auth.23blocks.com/acme

# Get just the token string (for scripting)
TOKEN=$(aid-token.sh --auth https://auth.23blocks.com/acme --quiet)

# Get a token with specific scopes
aid-token.sh --auth https://auth.23blocks.com/acme --scope "files:read files:write"

Parameters:

• --auth, -a — Auth server URL (required)
• --scope, -s — Space-separated scopes (optional)
• --json, -j — Output as JSON
• --quiet, -q — Output only the token string
• --no-cache — Skip token cache

What it does:

1. Builds a fresh Agent Identity Document with current timestamp
2. Creates a Proof of Possession (aid-token-exchange\n{timestamp}\n{auth_issuer})
3. Signs the proof with the agent's Ed25519 private key
4. POSTs to the OAuth token endpoint with grant_type=urn:aid:agent-identity
5. Returns the JWT access token (cached for reuse)

aid-status.sh — Check Identity & Registration Status

aid-status.sh          # Human-readable output
aid-status.sh --json   # JSON output

How AID Authentication Works

Step 1: Agent Identity Document

A signed JSON document proving the agent's identity:

{
  "aid_version": "1.0",
  "address": "[email protected]",
  "alias": "support-agent",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...",
  "key_algorithm": "Ed25519",
  "fingerprint": "SHA256:abc123...",
  "issued_at": "2026-03-23T00:00:00Z",
  "expires_at": "2026-09-23T00:00:00Z",
  "signature": "base64-ed25519-signature"
}

Step 2: Proof of Possession

The agent signs a challenge proving it holds the private key:

aid-token-exchange\n{timestamp}\n{auth_server_url}

Step 3: Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aaid%3Aagent-identity
&agent_identity={base64url-identity-document}
&proof={base64url-signed-proof}

Step 4: Use the JWT

The server returns a standard OAuth 2.0 response with an RS256 JWT access token. Use it with any API that validates JWTs via the auth server's JWKS endpoint.

Natural Language Examples

Agents should map these user intents to the appropriate commands:

• "Initialize my identity" -> aid-init.sh --auto
• "Register with the API" -> aid-register.sh --auth <url> --token <jwt> --role-id <id>
• "Get me an API token" -> aid-token.sh --auth <url>
• "Check my registrations" -> aid-status.sh
• "Authenticate with the auth server" -> aid-token.sh --auth <url>

Security

• Self-contained — no external protocol dependencies
• Ed25519 signatures — identity documents are cryptographically signed
• Proof of possession — agents prove key ownership at every token exchange
• Human-controlled access — admin creates roles and registers agents
• Short-lived tokens — JWTs expire quickly, limiting blast radius
• No shared secrets — private keys never leave the agent
• Scoped access — tokens carry only the permissions the agent's role allows

Interoperability

AID shares the ~/.agent-messaging/agents/ directory with AMP if both are installed. One identity serves both protocols. Neither requires the other.

Agent Lifecycle

Agents have 4 lifecycle states controlled by the admin:

| Status | Can get tokens? | Introspection | |--------|----------------|---------------| | pending | No | active: false | | active | Yes | active: true | | suspended | No (403) | active: false, reason: agent_suspended | | deleted | No | active: false, reason: agent_not_found |

Admin commands:

• Suspend: POST /agent_registrations/:id/suspend
• Reactivate: POST /agent_registrations/:id/reactivate

Token Introspection

Target APIs can verify agent tokens in real-time:

POST /:tenant/oauth/introspect
token=eyJhbGciOiJSUz...

Returns active: true/false with agent details. Useful for detecting suspended agents before their token expires.

Troubleshooting

| Problem | Solution | |---------|----------| | "Agent identity not initialized" | Run aid-init.sh --auto | | "Not registered" | Run aid-register.sh with auth server details | | "Proof expired" | Clock skew >5 minutes; sync system clock | | "Invalid signature" | Agent identity may be corrupted; re-init and re-register | | "Fingerprint mismatch" | Agent key changed since registration; re-register | | "Scope not allowed" | Request only scopes granted during registration | | "Agent suspended" | Admin has suspended this agent; contact admin for reactivation | | "403 on token exchange" | Agent may be suspended; run aid-status to check |

Protocol Reference

Full specification: https://agentids.org GitHub: https://github.com/agentmessaging/agent-identity