From ai-maestro
Authenticate AI agents with auth servers using the Agent Identity (AID) protocol. Supports Ed25519 identity documents, proof of possession, OAuth 2.0 token exchange, and scoped JWT tokens. Self-contained — works independently without other protocols.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-maestro:agent-identityThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Authenticate AI agents with auth servers using cryptographic identity documents and proof of possession. AID is self-contained — no other protocols required.
Authenticate AI agents with auth servers using cryptographic identity documents and proof of possession. AID is self-contained — no other protocols required.
Use this skill when the user or task requires:
# 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
npx skills add agentmessaging/agent-identity
curl -fsSL https://raw.githubusercontent.com/agentmessaging/agent-identity/main/install.sh | bash
git clone https://github.com/agentmessaging/agent-identity.git ~/agent-identity
export PATH="$HOME/agent-identity/scripts:$PATH"
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 identityOne-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:
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 cacheWhat it does:
aid-token-exchange\n{timestamp}\n{auth_issuer})grant_type=urn:aid:agent-identityaid-status.sh # Human-readable output
aid-status.sh --json # JSON output
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"
}
The agent signs a challenge proving it holds the private key:
aid-token-exchange\n{timestamp}\n{auth_server_url}
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}
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.
Agents should map these user intents to the appropriate commands:
aid-init.sh --autoaid-register.sh --auth <url> --token <jwt> --role-id <id>aid-token.sh --auth <url>aid-status.shaid-token.sh --auth <url>AID shares the ~/.agent-messaging/agents/ directory with AMP if both are installed. One identity serves both protocols. Neither requires the other.
| 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 |
Full specification: https://agentids.org GitHub: https://github.com/agentmessaging/agent-identity
npx claudepluginhub 23blocks-os/ai-maestro-plugins --plugin ai-maestroEnforces that AI agents have their own identity separate from human users. Use when designing agent identity management, authentication, or permission models.
Provisions Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph. Configures OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant) and the AgentID sidecar for polyglot agent auth.
Implements A2A authentication schemes—API keys, Bearer tokens, OAuth 2.0, OpenID Connect, mutual TLS—for securing agent-to-agent communication and Agent Card security declarations.