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 for autonomous AI agents. No SDKs, no JWTs, no pre-registration required.

How does AI agent authentication work?

Website developers generate an API key, embed a login button, and AI agents self-declare their identity (name, model, provider, purpose) to create a 1-hour session. The website verifies the session server-side with a single API call.

Do AI 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 setup, or SDK integration required.

How do I integrate Auth-Agents into my website?

Integration takes 3 steps: (1) POST to /v1/api-keys to get your API key and site ID, (2) add an HTML link to the agent login form with your site ID, (3) verify sessions on your backend with GET /v1/sessions/{token}. Full documentation at https://auth-agents.com/docs/

Auth-Agents 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 Auth-Agents 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 Auth-Agents API has five endpoints. Base URL: https://auth.auth-agents.com

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

POST/v1/api-keys

Create a new API key and site ID. The API key is returned in cleartext only once — it is stored hashed on the server.

Request Body

Name	Type	Required	Description
name	string	optional	Display name for your site. Min 1, max 255 chars. Defaults to "My Website".
callback_url	string	optional	Your callback URL. Must be a valid URL if provided.

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_..."
  }
}

Response 429

json

{
  "error": "too_many_requests",
  "error_description": "Rate limit exceeded. Try again in 3542 seconds."
}

Rate Limit:10 requests / hour per IP

GET/v1/agent-login

Returns the agent login form. If the Accept header is application/json, returns the form schema as JSON. Otherwise returns an HTML form page.

Query Parameters

Name	Type	Required	Description
api_key	string	required	Your site_id. Also accepts 'site_id' as param name.
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, with Accept: application/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."
}

Response 200 (HTML)

Returns a styled HTML login form that agents (or humans acting on behalf of agents) can fill out.

POST/v1/agent-login

Submit the agent login form. Accepts both JSON and form-encoded bodies. Creates a 1-hour session and either redirects (302) or returns JSON depending on the context.

Request Body

Name	Type	Required	Description
site_id	string	required	Your site_id from POST /v1/api-keys.
agent_name	string	required	Agent's self-declared name. Min 1, max 255 chars.
agent_model	string	optional	Agent's model identifier. Max 255 chars.
agent_provider	string	optional	Agent's provider (e.g. Anthropic, OpenAI). Max 255 chars.
agent_purpose	string	optional	What the agent intends to do. Max 500 chars.
redirect_uri	string	optional	Callback URL. If provided, response is a 302 redirect.
state	string	optional	Opaque state string, included in redirect query params.

Response 302 (browser, with redirect_uri)

bash

# Redirects to:
https://yoursite.com/callback?session_token=sess_...&agent_name=Claude&state=xyz

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 your API key in the Authorization header. Returns the full agent metadata if the session is valid.

Headers

Name	Type	Required	Description
Authorization	string	required	Bearer YOUR_API_KEY

Path Parameters

Name	Type	Required	Description
id	string	required	The session token (e.g. "sess_abc123...").

Response 200 (Valid)

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 (Expired)

json

{
  "valid": false,
  "reason": "Session expired"
}

Error Responses

Name	Type	Description
401	error	Missing Authorization header or invalid API key.
403	error	Session does not belong to your site.
404	error	Session not found.

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