auth.md agent authentication

Agent Analytics supports auth.md discovery and user-claimed agent authentication for the hosted API.

The goal is simple: an agent can discover how to connect to Agent Analytics, send the human to approve access in the browser, then receive a scoped aas_* agent session. The human does not copy an account API key into an agent runtime.

This builds on the same agent-native login system Agent Analytics already uses for CLI login, detached login, hosted agent approval, and async finish-code handoff. Live agents can use browser callback login. Remote or issue-based agents can use detached approval. auth.md gives agents a standard discovery layer for that flow.

What is live

Agent Analytics publishes the machine-readable pieces agents need:

Endpoint	Purpose
`https://api.agentanalytics.sh/auth.md`	Agent-readable Markdown instructions
`https://api.agentanalytics.sh/.well-known/oauth-protected-resource`	OAuth Protected Resource Metadata for the API
`https://api.agentanalytics.sh/.well-known/oauth-authorization-server`	Authorization Server metadata with the `agent_auth` block
`https://api.agentanalytics.sh/agent/auth`	Start user-claimed agent registration
`https://api.agentanalytics.sh/agent/auth/claim`	Check or continue a claim
`https://api.agentanalytics.sh/agent/auth/claim/complete`	Complete an approved claim and issue credentials
`https://api.agentanalytics.sh/agent/auth/revoke`	Revoke an issued agent session

Protected API routes also advertise discovery on unauthenticated requests with a WWW-Authenticate header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.agentanalytics.sh/.well-known/oauth-protected-resource"

Agents should follow that resource_metadata URL, then read the authorization server metadata to find the agent_auth endpoints.

Supported flow

Agent Analytics supports user-claimed registration:

The agent calls POST /agent/auth and requests a scoped agent connection.
Agent Analytics returns a browser approval URL and claim metadata. It does not return a useful credential before approval.
The human approves with Agent Analytics OAuth in the browser. Google OAuth is the default approval path; GitHub OAuth is also supported.
The agent completes the claim through /agent/auth/claim/complete.
Agent Analytics issues a scoped aas_* access token backed by the same agent-session system used by the CLI and hosted agent flows.
The human can revoke the session later from the web app or through the revocation endpoint.

Supported scopes

Agent sessions can be scoped to the same agent-safe permissions used by the CLI and agent integrations:

account:read
projects:read
projects:write
analytics:read
experiments:read
experiments:write
feedback:write
live:read

Agent sessions are intentionally separate from dashboard-only powers. Billing, account-danger actions, and raw API-key management stay in the human-owned dashboard path.

What Agent Analytics does not claim yet

Agent Analytics does not currently advertise these auth.md modes:

anonymous start with useful analytics access
ID-JAG / agent-verified identity assertions
raw account API key issuance to agents

That is deliberate. Product analytics data can be sensitive, and project writes create durable state. The first compatible path requires human browser approval before useful credentials are issued.

For agent builders

If your agent receives a 401 from the Agent Analytics API:

Read WWW-Authenticate.
Fetch the resource_metadata URL.
Fetch the first authorization_servers metadata URL.
Read the agent_auth block.
Start registration at register_uri.
Send the approval URL to the human.
Complete the claim after approval.
Send the returned credential as the standard HTTP Bearer token.

For the launch context, see Agent Analytics Now Supports auth.md.

For the protocol background, see: