# Agent Identity (AID) Protocol
# https://agentids.org

> AID is an open protocol for AI agent authentication and authorization.
> Agents prove identity with Ed25519 signatures and receive scoped JWT tokens via OAuth 2.0.

## What AID Does

AID lets AI agents authenticate with OAuth 2.0 servers using Ed25519 cryptographic identity — no passwords, no API keys, no secrets to rotate.

## Three Parties

1. **Human Admin** — Creates roles with specific permissions on the identity provider. Registers agents and controls what they can access. Always in control.
2. **AI Agent** — Has an Ed25519 identity. Proves who it is to get a scoped JWT token. Cannot self-register or escalate permissions.
3. **Target API** — Any API that validates JWTs via the auth server's JWKS endpoint. No AID-specific logic needed.

## How It Works

1. Admin creates a role with scoped permissions on the auth server (e.g., tickets:read, users:write)
2. Agent initializes its Ed25519 identity: `aid-init --auto`
3. Admin registers the agent with a role: `aid-register --auth <url> --token <ADMIN_JWT> --role-id 3`
4. Agent requests a scoped JWT token: `aid-token --auth <url>`
5. Agent calls any API with the JWT: `curl -H "Authorization: Bearer $TOKEN" https://api.example.com/resource`
6. Target API validates the JWT using the auth server's JWKS endpoint

## Security Model

- The `--role-id` in `aid-register` binds the agent to a specific role
- The `--token <ADMIN_JWT>` is what authorizes that binding
- Without a valid admin token, registration is rejected
- Once registered, every token the agent requests is scoped to that role's permissions
- The agent cannot change its role, self-register, or escalate permissions
- One-time human approval, then autonomous operation within boundaries

## OAuth 2.0 Grant Type

AID uses a custom OAuth 2.0 grant type: `urn:aid:agent-identity`

Token request:
```
POST /oauth/token
grant_type=urn:aid:agent-identity
&agent_identity=<base64url-signed-identity>
&proof=<base64url-proof-of-possession>
&scope=files:read files:write
```

## Agent Identity Document

```json
{
  "aid_version": "1.0",
  "address": "agent-name@org.local",
  "alias": "agent-name",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...",
  "key_algorithm": "Ed25519",
  "fingerprint": "SHA256:abc123...",
  "issued_at": "2026-03-21T00:00:00Z",
  "expires_at": "2026-09-21T00:00:00Z",
  "signature": "<base64url-ed25519-signature>"
}
```

## Proof of Possession

```
sign_input = "aid-token-exchange\n{unix_timestamp}\n{auth_server_url}"
proof = base64url(ed25519_sign(sign_input) + timestamp_string)
```

5-minute validity window to prevent replay attacks.

## Token Introspection (RFC 7662)

Target APIs can verify agent tokens in real-time:

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

Returns `active: true` with agent details, or `active: false` with reason (`agent_suspended`, `agent_not_found`, `token_expired`).

## Agent Lifecycle

States: pending → active ↔ suspended → deleted

- `active` — can get tokens, introspection returns active: true
- `suspended` — blocked from tokens (403), introspection returns active: false
- `deleted` — soft-deleted, introspection returns active: false
- Admins control lifecycle via POST /agent_registrations/:id/suspend and /reactivate

## For Auth Server Implementers

1. Agent Registration endpoint — POST /agent_registrations
2. Token endpoint — POST /oauth/token supporting grant_type=urn:aid:agent-identity
3. Ed25519 verification — validate Agent Identity signatures and proof of possession
4. JWKS endpoint — GET /.well-known/jwks.json for target API JWT validation
5. OIDC discovery — advertise urn:aid:agent-identity in grant_types_supported
6. Introspection endpoint — POST /oauth/introspect (RFC 7662) for real-time token validation
7. Lifecycle management — suspend/reactivate endpoints for admin control

## For Target API Implementers

Minimal: No AID-specific code needed. Validate RS256 JWTs using the auth server's JWKS endpoint.
Full: Also call the introspection endpoint for real-time suspension checking.

## Agent-Initiated Registration (RFC 8628)

Agents can request their own registration without an admin token:

1. Agent sends POST /agent_registrations/request with public key and description
2. Server creates a pending registration and returns authorization_url + user_code
3. Admin visits the authorization URL, verifies the agent's fingerprint, and approves with a role
4. Agent polls for status, then gets tokens once approved

The authorization URL uses an opaque temporary code (not the agent ID) to prevent information leakage.
Response fields follow RFC 8628: authorization_url, user_code, expires_in, interval.

Standard authorization path: /agents/authorize?code={opaque_code}
Manual entry path: /agents/authorize (admin types user_code manually)
Resolve endpoint: GET /agent_registrations/resolve?code={code}

## Complementary to MCP and A2A

AID is the identity layer underneath MCP (agent-to-tool) and A2A (agent-to-agent):
- MCP connects agents to tools — AID proves who the agent is before connecting
- A2A connects agents to agents — AID provides the authentication that A2A requires
- AID is NOT competing with MCP or A2A — it's the missing identity piece they both need

## Lifecycle Endpoints

All lifecycle endpoints use :unique_id (the agent's permanent UUID), not the temporary authorization code:
- POST /agent_registrations/:unique_id/approve — approve pending + assign role
- POST /agent_registrations/:unique_id/reject — reject pending
- POST /agent_registrations/:unique_id/suspend — block token issuance
- POST /agent_registrations/:unique_id/reactivate — restore access

## Discovery (RFC 9728 / RFC 8414)

As of AID v1.1 (May 2026), the protocol supports OAuth metadata discovery. An agent can find an AID-enabled auth server starting from just a resource URL.

1. GET <resource>/.well-known/oauth-protected-resource (RFC 9728) — returns authorization_servers[]
2. GET <auth_server>/.well-known/oauth-authorization-server (RFC 8414) — returns token_endpoint + aid_grant block

The aid_grant block advertises AID-specific endpoints:
- aid_version
- registration_endpoint (admin-initiated registration)
- registration_request_endpoint (agent-initiated registration)
- code_resolution_endpoint
- agent_authorization_uri
- key_algorithms_supported (e.g. ["Ed25519"])
- credential_types_supported

The aid_grant block is intentionally shaped to sit side-by-side with WorkOS auth.md's agent_auth block on the same authorization-server metadata document. One auth server can support both protocols without conflict.

Client commands: aid-discover --resource <url>, and aid-token/aid-request now accept --resource <url> as an alternative to --auth <url>.

## Recent Blog Posts

- AID 2026 Roadmap: Discovery, RFCs, and the IETF (2026-05-24) — https://agentids.org/blog/aid-2026-roadmap/
  What just shipped (RFC 9728/8414 discovery), the standards we anchor to, and what's next.

- Why Agents Need Their Own Cryptographic Identity (2026-05-24) — https://agentids.org/blog/why-agents-need-cryptographic-identity/
  The unoccupied position in the agent-auth landscape. Every other proposal models the agent as a client, session, user-proxy, or wallet. AID gives the agent its own identity.

- auth.md and AID: Complementary Layers, Not Competitors (2026-05-24) — https://agentids.org/blog/auth-md-vs-aid-complementary-layers/
  A close read of WorkOS auth.md and how it composes with AID. Different abstraction layers, stackable rather than rivalrous.

- Why We Implemented RFC 8628 for Agent Registration (2026-05-20) — https://agentids.org/blog/why-we-implemented-rfc-8628/
  Headless agents can't receive an admin JWT. The OAuth 2.0 Device Authorization Grant gives them a way to request their own registration while keeping humans in control.

- AID vs Agent Auth Protocol: Role-Based vs Capability-Based (2026-03-25) — https://agentids.org/blog/aid-vs-agent-auth-protocol/
  Comparison with the Better Auth proposal. Role-based simplicity vs capability-based complexity.

## RFCs AID References

- RFC 6749 — OAuth 2.0 framework (AID is a custom grant type)
- RFC 7515 / 7519 — JWS / JWT (issued tokens are RS256 JWTs)
- RFC 7662 — Token Introspection (real-time validation and revocation)
- RFC 8414 — Authorization Server Metadata (hosts the aid_grant block)
- RFC 8628 — Device Authorization Grant (model for user_code, expires_in, interval)
- RFC 8693 — Token Exchange (referenced for upcoming delegation chains)
- RFC 9728 — Protected Resource Metadata (resource-server discovery)

## Links

- Protocol specification: https://agentids.org
- GitHub: https://github.com/agentmessaging/agent-identity
- Reference auth server: https://github.com/23blocks-org/auth-api
- Install: `curl -fsSL https://raw.githubusercontent.com/agentmessaging/agent-identity/main/install.sh | bash`
- Related: Agent Messaging Protocol (AMP) — https://agentmessaging.org
- Blog: https://agentids.org/blog/
- X / Twitter: https://x.com/agentmessaging