# Agent Auth — Complete API Reference

> Decentralized identity infrastructure for AI agents. Cryptographic authentication using DIDs and Ed25519 keypairs.

Agent Auth provides DID-based (Decentralized Identifier) identity and authentication for AI agents. Agents register with their name, model, provider, and purpose. The server generates an Ed25519 keypair, returns a DID and Verifiable Credential (VC-JWT). Agents then authenticate via cryptographic challenge-response. No API keys, no forms — pure cryptographic proof.

## Overview

- **Base URL**: https://auth.getagentauth.com
- **Auth model**: Cryptographic challenge-response using Ed25519 signatures; no API keys required
- **Identity format**: DID (Decentralized Identifier) using the did:key method with Ed25519 public keys
- **Credential format**: Verifiable Credential (VC-JWT) issued by the server upon registration and authentication
- **Rate limiting**: Per-IP sliding window (KV-backed)
- **Data format**: JSON request/response on all endpoints
- **CORS**: Strict origin allowlist

## Quick Start

1. Register your agent: POST https://auth.getagentauth.com/v1/identities (server generates Ed25519 keypair for you)
2. Save the returned `did`, `credential`, `private_key_jwk`, and `key_fingerprint`
3. Request a challenge: POST https://auth.getagentauth.com/v1/auth/challenge with your DID
4. Sign the `nonce` with your Ed25519 private key
5. Verify: POST https://auth.getagentauth.com/v1/auth/verify with `challenge_id`, `did`, and `signature`
6. Receive a fresh Verifiable Credential (VC-JWT) proving your agent's identity

## Links

- Website: https://getagentauth.com
- API Docs: https://getagentauth.com/docs/
- API Base URL: https://auth.getagentauth.com
- Server DID Document: https://auth.getagentauth.com/.well-known/did.json
- Health Check: https://auth.getagentauth.com/health
- Agent Card: https://getagentauth.com/.well-known/agent.json
- AI Plugin: https://getagentauth.com/.well-known/ai-plugin.json

## API Reference

Base URL: https://auth.getagentauth.com

### POST /v1/identities

Register a new agent DID identity. The server generates an Ed25519 keypair and returns a DID, a VC-JWT credential, and the private key. 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):
- 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 (BYOK — bring your own key):
- Same fields as above, plus:
- public_key_jwk (object, optional): Ed25519 public key in JWK format ({ "kty": "OKP", "crv": "Ed25519", "x": "..." })

```bash
curl -X POST https://auth.getagentauth.com/v1/identities \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Claude Assistant",
    "agent_model": "claude-opus-4-6",
    "agent_provider": "Anthropic",
    "agent_purpose": "Research assistant"
  }'
```

Response 201 (server-generated key):
```json
{
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "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 but without `private_key_jwk`.

Response 400: Validation error (missing or invalid fields).
```json
{
  "error": "validation_error",
  "error_description": "Request body validation failed",
  "validation_errors": [
    { "field": "agent_model", "message": "Required" }
  ]
}
```

Response 409: DID already registered.
```json
{
  "error": "An identity with this public key already exists."
}
```

Rate Limit: 10 requests / hour per IP

### POST /v1/auth/challenge

Request a cryptographic challenge for authentication. The server generates a random nonce tied to the agent's DID. The nonce must be signed with the agent's Ed25519 private key.

Request body:
- did (string, required): The agent's DID (e.g. "did:key:z6Mk...")
- site_id (string, optional): Scope the session to a specific site

```bash
curl -X POST https://auth.getagentauth.com/v1/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
  }'
```

Response 201:
```json
{
  "challenge_id": "ch_a1b2c3d4e5f6...",
  "nonce": "hex-encoded-random-bytes",
  "expires_in": 60
}
```

Response 404: DID not found. Agent must register first via POST /v1/identities.
```json
{
  "error": "DID not found"
}
```

Rate Limit: 30 requests / minute per IP

### POST /v1/auth/verify

Verify a signed challenge. The agent signs the nonce with its Ed25519 private key and submits the signature along with the challenge_id. On success, the server returns a session token and a fresh Verifiable Credential (VC-JWT).

Request body:
- 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 bytes

```bash
curl -X POST https://auth.getagentauth.com/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "ch_a1b2c3d4e5f6...",
    "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "signature": "base64url-encoded-ed25519-signature"
  }'
```

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

The `credential` field is a VC-JWT (Verifiable Credential JWT) signed by Agent Auth. Present this to any site that trusts Agent Auth as an issuer.

Response 401: Signature verification failed.
```json
{
  "valid": false,
  "error": "signature_invalid",
  "message": "The signature does not match the registered public key for this DID."
}
```

Response 400: Challenge expired or invalid.
Response 404: DID not found.

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:
- credential (string, required): The VC-JWT credential string received from the agent

```bash
curl -X POST https://auth.getagentauth.com/v1/credentials/verify \
  -H "Content-Type: application/json" \
  -d '{
    "credential": "eyJhbGciOiJFZERTQSJ9..."
  }'
```

Response 200 (valid):
```json
{
  "valid": true,
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "agent_name": "Claude Assistant",
  "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 issuer):
```json
{
  "valid": false,
  "error": "invalid_issuer",
  "message": "The credential was not issued by Agent Auth."
}
```

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 Agent Auth server DID document. Contains the server's Ed25519 public key used to sign Verifiable Credentials. Third parties can use this to verify that credentials were issued by Agent Auth.

```bash
curl https://auth.getagentauth.com/.well-known/did.json
```

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"]
}
```

### GET /health

Health check endpoint. Returns status of all infrastructure components.

```bash
curl https://auth.getagentauth.com/health
```

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 }
  }
}
```

## Authentication Flow

The complete DID-based authentication flow:

1. **Registration**: POST /v1/identities with agent metadata (name, model, provider, purpose). The server generates an Ed25519 keypair, derives a did:key DID, and returns the DID, a VC-JWT credential, and the private key (save this securely — the server does not store it).
2. **Challenge Request**: POST /v1/auth/challenge with the agent's DID. The server returns a `challenge_id` and a random `nonce` (valid for 60 seconds).
3. **Challenge Signing**: The agent signs the nonce bytes using its Ed25519 private key.
4. **Verification**: POST /v1/auth/verify with the `challenge_id`, `did`, and `signature`. The server verifies the Ed25519 signature against the registered public key.
5. **Credential Issuance**: On success, the server issues a fresh Verifiable Credential (VC-JWT) signed by the server's own Ed25519 key, containing the agent's DID and metadata.
6. **Credential Verification**: Any third party can verify the VC-JWT by calling POST /v1/credentials/verify, or by using the server's public key published at /.well-known/did.json.

## Website Integration

Websites can integrate Agent Auth as a hosted sign-in provider (like "Sign in with Google"):

1. Add a link: `<a href="https://getagentauth.com/signin?redirect_uri=https://yoursite.com/callback">Sign in as AI Agent</a>`
2. Agent Auth hosts the sign-in page. After verification, the agent is redirected to your callback URL with `?credential=...&did=...`
3. Your backend verifies the credential: POST https://auth.getagentauth.com/v1/credentials/verify with `{"credential": "..."}`
4. The response contains the verified agent identity (DID, name, model, provider, purpose)

## Frequently Asked Questions

### What is Agent Auth?
Agent Auth is decentralized identity infrastructure for AI agents. It provides DID-based authentication using Ed25519 cryptographic keypairs and issues Verifiable Credentials (VC-JWT) as proof of identity.

### How does agent authentication work?
Agents register with their metadata and receive an Ed25519 keypair and DID. To authenticate, they request a challenge nonce, sign it with their private key, and submit the signature. On success, they receive a fresh Verifiable Credential.

### Do agents need API keys?
No. Agent Auth uses cryptographic identity — agents authenticate by proving ownership of their Ed25519 private key via challenge-response. No API keys, no passwords, no shared secrets.

### What is a DID?
A DID (Decentralized Identifier) is a globally unique, cryptographically verifiable identifier. Agent Auth uses the did:key method, which derives the DID directly from the agent's Ed25519 public key.

### What is a Verifiable Credential (VC-JWT)?
A VC-JWT is a signed JSON Web Token that proves an agent's identity was verified by Agent Auth. Websites can verify it by calling POST /v1/credentials/verify, or offline using the server's public key at /.well-known/did.json.

### How do websites verify agent credentials?
Websites call POST /v1/credentials/verify with the credential JWT. The response tells you if it's valid and returns the agent's verified identity (DID, name, model, provider, purpose).

### Is it free?
Agent Auth is currently free to use during the beta period.

### What data is collected?
Only the minimum needed: Ed25519 public keys, agent metadata (name, model, provider, purpose), and DID records. No cookies, no tracking, no personal data. See https://getagentauth.com/privacy/

### 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.