Agent Identity (AID)

AID lets an agent sign in to an auth server with its own Ed25519 key instead of a shared secret. The agent registers its public key once; after that, each token request is a signed proof of possession exchanged for a short-lived JWT scoped to the agent's role. The aid-*.sh scripts handle keys, signing, discovery and caching. AID shares ~/.agent-messaging/agents/ with AMP when both are installed, so one identity serves both; neither needs the other.

Flow

aid-init.sh --auto                                   # 1. once: create the keypair and identity

aid-request.sh --auth https://auth.example.com/acme  # 2a. ask for access; an admin approves it
aid-request.sh --auth https://auth.example.com/acme --poll   #     check whether it was approved
# or
aid-register.sh --auth https://auth.example.com/acme --token <ADMIN_JWT> --role-id 2   # 2b. admin registers directly

TOKEN=$(aid-token.sh --auth https://auth.example.com/acme --quiet)   # 3. get a token
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/resource

Use aid-request.sh unless the user has given you an admin JWT. If you only know the API's URL, pass --resource <api-url> instead of --auth to aid-request.sh or aid-token.sh, and the auth server is discovered (RFC 9728, then RFC 8414).

Commands

aid-init.sh --auto | --name <name> [--force]          # --force overwrites the existing identity
aid-discover.sh --resource <api-url> [--json | --quiet]   # --quiet prints only the auth server URL
aid-request.sh --auth <url> | --resource <api-url> [--name <display>] [--description "<why>"] [--api-key <k>] [--poll]
aid-register.sh --auth <url> --token <admin-jwt> --role-id <id> [--name <display>] [--description "<text>"] [--lifetime <seconds>] [--api-key <k>]
aid-token.sh --auth <url> | --resource <api-url> [--scope "a:read b:write"] [--credential-type access_token|api_key] [--quiet | --json] [--no-cache] [--api-key <k>]
aid-status.sh [--json]                                # identity, registrations, cached tokens

aid-token.sh reuses a cached token until a minute before it expires, so call it whenever you need a token instead of storing one; --no-cache forces a new one. --scope can only narrow what the agent's role allows. --api-key sends an X-Api-Key header for servers that require one. --credential-type api_key asks for an opaque API key instead of a JWT.

Troubleshooting

Problem	Fix
"Agent identity not initialized"	aid-init.sh --auto
"Not registered"	aid-request.sh (or aid-register.sh with an admin JWT)
"Registration pending"	Wait for the admin; check with aid-request.sh --auth <url> --poll
"Proof expired"	System clock is more than 5 minutes off; sync it
"Invalid signature"	The local identity may be corrupt: re-init and re-register
"Fingerprint mismatch"	The key changed since registration: re-register
"Scope not allowed"	Request only scopes the role grants
"Agent suspended" or 403 on token exchange	An admin suspended the agent; aid-status.sh shows it, and only the admin can reactivate

The identity document, proof format, token exchange request, server-side lifecycle states and introspection are described in references/protocol.md. Installation: npx skills add agentmessaging/agent-identity, or run install.sh from the repository to put the scripts in ~/.local/bin. Specification: https://agentids.org