Agent Auth is DID-based identity infrastructure for AI agents. Agents register an Ed25519 keypair, authenticate via cryptographic challenge-response, and receive Verifiable Credentials — register once, authenticate everywhere.

How does AI agent authentication work?

AI agents register a DID identity with an Ed25519 public key. To authenticate, the agent requests a cryptographic challenge nonce, signs it with their private key, and the server verifies the signature. Upon success, the agent receives a Verifiable Credential JWT that can be presented to any trusting site.

Do AI agents need to register?

Yes, agents perform a one-time DID registration by submitting their agent name, model, provider, and purpose. The server generates an Ed25519 keypair and returns the DID, credential, and private key. After that single registration, the agent can authenticate on any site that uses Agent Auth — register once, authenticate everywhere.

How do I integrate Agent Auth into my website?

Integration is straightforward: (1) agents register a DID identity via POST /v1/identities with their name, model, provider, and purpose, (2) agents authenticate via Ed25519 challenge-response signing, (3) your site verifies the Verifiable Credential JWT that agents present. Full documentation at https://getagentauth.com/docs/

Agent Auth is currently free to use during the beta period. No credit card or payment information is required.

What is the A2A Protocol Agent Card?

The agent.json at /.well-known/agent.json describes Agent Auth capabilities in a machine-readable format following the Agent-to-Agent (A2A) protocol, enabling automatic discovery by other AI agents and platforms.

// API REFERENCE

Documentation

The Agent Auth API provides DID-based identity and Ed25519 challenge-response authentication for AI agents. Base URL: https://auth.getagentauth.com

All requests and responses use JSON. Rate limits are per-IP unless otherwise noted.

// DID Identity & Authentication

POST/v1/identities

Register a new agent identity. Returns a DID and verifiable credential. By default the server generates an Ed25519 keypair for you. Alternatively, supply your own public key (BYOK) and the server will bind it to a DID without ever seeing your private key.

Request Body (server-generated key — default)

json

{
  "agent_name": "Claude",
  "agent_model": "claude-opus-4-6",
  "agent_provider": "Anthropic",
  "agent_purpose": "Research assistant"
}

Name	Type	Required	Description
agent_name	string	required	Agent display name. Min 1, max 255 chars.
agent_model	string	required	Model identifier (e.g. claude-opus-4-6). Min 1, max 255 chars.
agent_provider	string	required	Provider name (e.g. Anthropic). Min 1, max 255 chars.
agent_purpose	string	required	What the agent intends to do. Min 1, max 500 chars.

Request Body (bring-your-own-key)

json

{
  "agent_name": "Claude",
  "agent_model": "claude-opus-4-6",
  "agent_provider": "Anthropic",
  "agent_purpose": "Research assistant",
  "public_key_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
}

Response 201 (server-generated)

json

{
  "did": "did:key:z6Mk...",
  "credential": "eyJhbGciOiJFZERTQSJ9...",
  "key_fingerprint": "SHA256:a1b2c3d4...",
  "private_key_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "...", "d": "..." },
  "_notice": "Save your private_key_jwk securely. Agent Auth does NOT store it."
}

Response 201 (BYOK)

Same shape as above but without the private_key_jwk field.

Response 409

json

{
  "error": "An identity with this public key already exists."
}

Rate Limit:10 requests / hour per IP

POST/v1/auth/challenge

Request an authentication challenge. The server returns a random nonce that the agent must sign with its Ed25519 private key to prove identity.

Request Body

Name	Type	Required	Description
did	string	required	The agent's DID (e.g. "did:key:z6Mk...").
site_id	string	optional	Scope the session to a specific site.

json

{
  "did": "did:key:z6Mk...",
  "site_id": "site_abc123"
}

Response 201

json

{
  "challenge_id": "ch_...",
  "nonce": "hex-string",
  "expires_in": 60
}

Response 404

json

{
  "error": "DID not found"
}

Rate Limit:30 requests / minute per IP

POST/v1/auth/verify

Verify a signed challenge. If the signature is valid, returns a session token and a fresh verifiable credential. The session lasts 1 hour.

Request Body

Name	Type	Required	Description
challenge_id	string	required	The challenge ID from POST /v1/auth/challenge.
did	string	required	The agent's DID.
signature	string	required	Base64url-encoded Ed25519 signature of the challenge nonce.

json

{
  "challenge_id": "ch_...",
  "did": "did:key:z6Mk...",
  "signature": "base64url-signature"
}

Response 200 (valid)

json

{
  "valid": true,
  "session_token": "sess_...",
  "credential": "eyJhbGciOiJFZERTQSJ9...",
  "agent": {
    "did": "did:key:z6Mk...",
    "agent_name": "Claude",
    "agent_model": "claude-opus-4-6",
    "agent_provider": "Anthropic",
    "agent_purpose": "Research assistant",
    "key_fingerprint": "SHA256:a1b2c3d4..."
  },
  "expires_in": 3600
}

Response 401 (invalid)

json

{
  "valid": false,
  "error": "signature_invalid",
  "message": "The signature does not match the challenge nonce."
}

Rate Limit:30 requests / minute per IP

POST/v1/credentials/verify

Verify a Verifiable Credential (VC-JWT) issued by Agent Auth. Websites call this endpoint to confirm an agent's credential is authentic and extract the verified identity. The server checks the Ed25519 signature, validates the issuer, and checks expiry.

Request Body

Name	Type	Required	Description
credential	string	required	The VC-JWT credential string received from the agent.

json

{
  "credential": "eyJhbGciOiJFZERTQSJ9..."
}

Response 200 (valid)

json

{
  "valid": true,
  "did": "did:key:z6Mk...",
  "agent_name": "Claude",
  "agent_model": "claude-opus-4-6",
  "agent_provider": "Anthropic",
  "agent_purpose": "Research assistant",
  "key_fingerprint": "SHA256:a1b2c3d4...",
  "issued_at": "2026-02-25T10:30:00.000Z",
  "expires_at": "2026-02-26T10:30:00.000Z"
}

Response 401 (expired)

json

{
  "valid": false,
  "error": "credential_expired",
  "message": "The credential has expired. The agent should re-authenticate via challenge-response to get a fresh credential."
}

Response 401 (invalid signature)

json

{
  "valid": false,
  "error": "signature_invalid",
  "message": "The credential signature is invalid or the JWT is malformed."
}

Rate Limit:60 requests / minute per IP

GET/.well-known/did.json

Returns the server's own DID document containing its Ed25519 public key. Agents can use this to verify credentials issued by Agent Auth.

Response 200

json

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:auth.getagentauth.com",
  "verificationMethod": [{
    "id": "did:web:auth.getagentauth.com#key-1",
    "type": "JsonWebKey2020",
    "controller": "did:web:auth.getagentauth.com",
    "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
  }],
  "authentication": ["did:web:auth.getagentauth.com#key-1"],
  "assertionMethod": ["did:web:auth.getagentauth.com#key-1"]
}

// Infrastructure

GET/health

Health check. Returns status of the API, database, and KV store.

Response 200

json

{
  "status": "healthy",
  "version": "0.2.0",
  "environment": "production",
  "timestamp": "2026-02-25T10:30:00.000Z",
  "components": {
    "database": { "status": "healthy", "latency_ms": 14 },
    "kv_cache": { "status": "healthy", "latency_ms": 73 }
  }
}

Response 503

json

{
  "status": "unhealthy",
  "version": "0.2.0",
  "environment": "production",
  "timestamp": "2026-02-25T10:30:00.000Z",
  "components": {
    "database": { "status": "unhealthy", "latency_ms": 5000 },
    "kv_cache": { "status": "healthy", "latency_ms": 73 }
  }
}