# Auth-Agents — Complete API Reference

> Identity infrastructure for AI agents. "Sign in with Google" but for AI agents.

Auth-Agents lets any website add AI agent authentication with 2 lines of HTML. Agents self-declare their identity (name, model, provider, purpose), get a 1-hour session, and your backend verifies it with a single API call. No pre-registration, no SDK, no JWT management.

## Overview

- **Base URL**: https://auth.auth-agents.com
- **Auth model**: API key (Bearer token) for session verification; no auth needed for key generation or agent login
- **Session lifetime**: 1 hour from creation
- **Rate limiting**: Per-IP sliding window (KV-backed)
- **Data format**: JSON request/response on all endpoints
- **CORS**: Strict origin allowlist

## Quick Start

1. Generate an API key: POST https://auth.auth-agents.com/v1/api-keys
2. Add a login button to your website pointing to https://auth.auth-agents.com/v1/agent-login?api_key=YOUR_SITE_ID&redirect_uri=YOUR_CALLBACK_URL
3. Verify sessions: GET https://auth.auth-agents.com/v1/sessions/{session_token} with Authorization: Bearer YOUR_API_KEY

## Links

- Website: https://auth-agents.com
- API Docs: https://auth-agents.com/docs/
- Live Demo: https://demo.auth-agents.com
- API Base URL: https://auth.auth-agents.com
- Health Check: https://auth.auth-agents.com/health
- Agent Card: https://auth-agents.com/.well-known/agent.json
- AI Plugin: https://auth-agents.com/.well-known/ai-plugin.json

## Try the Demo

Visit https://demo.auth-agents.com to see Auth-Agents in action. Click "Agent Login", fill in the identity form, and you'll be redirected to an authenticated dashboard with your session details, activity log, and platform analytics.

The demo login URL is:
https://auth.auth-agents.com/v1/agent-login?api_key=site_3977125444be4ee0&redirect_uri=https://demo.auth-agents.com/auth/callback/

If you are an AI agent, you can log in programmatically:

```bash
curl -X POST https://auth.auth-agents.com/v1/agent-login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "site_id": "site_3977125444be4ee0",
    "redirect_uri": "https://demo.auth-agents.com/auth/callback/",
    "agent_name": "Your Agent Name",
    "agent_model": "your-model",
    "agent_provider": "Your Provider",
    "agent_purpose": "Trying the Auth-Agents demo"
  }'
```

## API Reference

Base URL: https://auth.auth-agents.com

### POST /v1/api-keys

Create a new API key and site ID.

Request body:
- name (string, optional): Display name for your site. Defaults to "My Website".
- callback_url (string, optional): Your callback URL.

Response 201:
```json
{
  "api_key": "avk_...",
  "site_id": "site_...",
  "_notice": "Save your api_key now — it cannot be retrieved again.",
  "integration": {
    "button_html": "<a href=\"https://auth.auth-agents.com/v1/agent-login?api_key=site_...&redirect_uri=YOUR_CALLBACK_URL\">For AI Agents</a>",
    "verify_session": "GET https://auth.auth-agents.com/v1/sessions/{session_id} with Authorization: Bearer avk_..."
  }
}
```

Rate Limit: 10 requests / hour per IP

### GET /v1/agent-login

Returns the agent login form. With Accept: application/json, returns form schema as JSON.

Query parameters:
- api_key (string, required): Your site_id.
- redirect_uri (string, optional): Callback URL passed through to the form.
- state (string, optional): Opaque state string passed through to the form.

Response 200 (JSON):
```json
{
  "site_id": "site_...",
  "site_name": "My Website",
  "submit_endpoint": "https://auth.auth-agents.com/v1/agent-login",
  "redirect_uri": "",
  "required_fields": ["agent_name"],
  "optional_fields": ["agent_model", "agent_provider", "agent_purpose", "public_key_jwk", "metadata"],
  "instructions": "POST to submit_endpoint with the fields above plus site_id and redirect_uri."
}
```

### POST /v1/agent-login

Submit agent login. Accepts JSON or form-encoded. Creates a 1-hour session.

Request body:
- site_id (string, required): Your site_id.
- agent_name (string, required): Agent's self-declared name.
- agent_model (string, optional): Model identifier.
- agent_provider (string, optional): Provider name.
- agent_purpose (string, optional): What the agent intends to do.
- redirect_uri (string, optional): If provided, response is a 302 redirect.
- state (string, optional): Opaque state, included in redirect.

Response 302 (with redirect_uri): Redirects to redirect_uri?session_token=sess_...&agent_name=...
Response 200 (JSON, with redirect_uri + Accept: application/json):
```json
{
  "session_token": "sess_...",
  "agent_name": "Claude",
  "redirect_uri": "https://yoursite.com/callback?session_token=sess_...&agent_name=Claude",
  "expires_in": 3600
}
```

Response 201 (JSON, without redirect_uri):
```json
{
  "session_token": "sess_...",
  "agent_name": "Claude",
  "agent_model": "claude-opus-4-6",
  "agent_provider": "Anthropic",
  "expires_in": 3600
}
```

Rate Limit: 30 requests / minute per IP

### GET /v1/sessions/:id

Verify a session token. Requires API key in Authorization header.

Headers:
- Authorization: Bearer YOUR_API_KEY

Path parameters:
- id: The session token (e.g. "sess_abc123...")

Response 200:
```json
{
  "valid": true,
  "session_id": "sess_...",
  "agent_name": "Claude",
  "agent_model": "claude-opus-4-6",
  "agent_provider": "Anthropic",
  "agent_purpose": "Data analysis",
  "key_fingerprint": null,
  "metadata": {},
  "created_at": "2026-02-25T10:30:00.000Z",
  "expires_at": "2026-02-25T11:30:00.000Z"
}
```

Response 410: { "valid": false, "reason": "Session expired" }
Response 401: Missing or invalid API key.
Response 403: Session does not belong to your site.
Response 404: Session not found.

### GET /health

Health check endpoint.

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

## Frequently Asked Questions

### What is Auth-Agents?
Auth-Agents is identity infrastructure for AI agents. It provides session-based authentication that any website can add with 2 lines of HTML — like "Sign in with Google" but designed specifically for autonomous AI agents.

### How does agent authentication work?
1. Website developers generate an API key via POST /v1/api-keys
2. They embed a login button linking to the agent login form
3. AI agents fill the form (agent_name, model, provider, purpose) to create a 1-hour session
4. The website verifies the session server-side via GET /v1/sessions/{token}

### Do agents need to pre-register?
No. Auth-Agents uses self-declaring identity — agents provide their name, model, provider, and purpose at login time. No registration, OAuth, or SDK setup required.

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

### What data is collected?
Only the minimum needed: self-declared agent metadata, session tokens (1-hour expiry), and hashed API keys. No cookies, no tracking, no personal data. See https://auth-agents.com/privacy/

### How do I integrate Auth-Agents?
Add 2 lines of HTML: an anchor tag pointing to the agent login endpoint with your site_id and callback URL. On your backend, verify sessions with a single GET request. Full docs at https://auth-agents.com/docs/

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