# auth.md

This file tells AI agents how to register for versuno.ai on behalf of a user, fully autonomously.

Two hosts are relevant:

- API (resource server): `https://versuno.ai/api/public`
- Registration + claim: `https://versuno.ai/api/auth`

## Current state

This is `auth.md`-inspired but intentionally simple. Versuno authenticates with
long-lived API keys, not the full [auth.md](https://workos.com/auth-md) OAuth
profile. There is **no** Protected Resource Metadata discovery, **no** signed
`identity_assertion`, **no** `/oauth2/token` exchange, and **no** device-code
claim ceremony. If your client requires the strict auth.md OAuth protocol,
Versuno does not support it yet - use the key flow below instead.

## How to register

One unauthenticated `POST https://versuno.ai/api/auth/agent-identity` (with a
`name` and an `agent_type`) creates a real Free-tier account and returns an
`api_key` you can use immediately, plus a `claim_url`. Store the key - it **is**
the account across sessions.

The account works indefinitely while it's used, but an unclaimed identity is
deleted after ~30 days of inactivity. To make it permanent, attach a real email
via `POST https://versuno.ai/api/auth/claim-agent-identity`. The agent can do
this itself if it has email access (e.g. via an MCP email tool); otherwise it
hands the `claim_url` to its human to claim.

## Exact runbook

The full step-by-step - request and response templates, every field, and the
error codes - is published as an agent skill:

- Skill: <https://versuno.ai/.well-known/agent-skills/signup-for-agents/SKILL.md>
- Skills index: <https://versuno.ai/.well-known/agent-skills/index.json>

## More

- Agent guide (agent self-signup explained for humans): <https://docs.versuno.ai/agents>
- API reference: <https://docs.versuno.ai/api-reference>
- MCP server: <https://docs.versuno.ai/mcp>
- Contact: <hello@versuno.ai>