Agents - Versuno Docs

The problem

Most AI agents can’t handle email verification - no inbox, and no clean way to get an API key without a human doing it for them. Versuno fixes this with a dedicated agent signup flow: one unauthenticated POST call returns a working API key instantly. No email, no verification, no dashboard visit required.

Agents can also discover this flow as a machine-readable file at versuno.ai/auth.md.

How it works

Agent calls POST /api/auth/agent-identity

The agent sends its name and type. Versuno creates a real account with a synthetic internal email and returns an API key plus a claim_url.

curl -X POST "https://versuno.ai/api/auth/agent-identity" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My coding assistant",
    "agent_type": "claude-code"
  }'

Response:

{
  "agent_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "handle": "my-coding-assistant",
  "api_key": "uk_live_...",
  "claim_url": "https://versuno.ai/claim/<token>",
  "message": "You're a temporary agent identity on the Free tier; your api_key works immediately. To make the account permanent, claim it: if you can access an email inbox (e.g. via an MCP email tool), POST a real email and password to /api/auth/claim-agent-identity and open the verification link yourself — no human needed. Otherwise, give the claim_url to your human to claim it. Unclaimed, idle identities are deleted after ~30 days."
}

Agent uses the API key immediately

The account is fully operational from the moment it’s created. The agent stores the api_key and can start reading and writing right away.

curl "https://versuno.ai/api/public/assets" \
  -H "Authorization: Bearer uk_live_..."

Claim the account (optional)

The account keeps working as long as the agent uses its api_key, but stays deletable while unclaimed. To make it permanent, the agent claims it or hands the claim_url to its human to claim. See Claiming the account.

Reusing the account across sessions

The api_key is the account. As long as the agent presents the same key, every session acts as the same account, with the same brains, assets, and usage history. A closed session is not a deleted account. So persist the key the first time you get it, somewhere that survives the session closing:

the agent’s own long-term memory or secret store,
a local config file or environment variable, or
handed to the human to keep.

A new session reuses the account by sending the stored key as Authorization: Bearer <key>.

There is no key-recovery endpoint, by design: the key is the only secret tied to an unclaimed identity, so handing it back to anyone who asked would be an account-takeover hole. If an unclaimed agent loses its key, just create a fresh identity with POST /api/auth/agent-identity. Once the account is claimed, the human can re-view the key anytime from the dashboard.

Temporary vs permanent accounts

	Unclaimed agent identity	Claimed account
Signup	Single API call, no email	Email + password submitted at claim URL
API access	Full Free tier	Full Free tier
Lifespan	Deleted after ~30 days of inactivity	Permanent
Email	Synthetic internal address	Real, verified email
Dashboard access	No	Yes

Agent identities are real Free-tier accounts. There is no feature restriction, reduced rate limit, or any functional difference from a regular Free account. The only difference is the inactivity reaper: unclaimed identities with no API activity for ~30 days are automatically deleted.

Claiming the account

Claiming attaches a real email to the identity, which makes it permanent and unlocks the dashboard. It’s a two-step handshake:

Start the claim

Either open the claim_url (a page with an email + password form) or POST the same fields straight to /api/auth/claim-agent-identity. Versuno emails a verification link to that address.

Open the verification link

Opening it finishes the claim: the real email replaces the synthetic one and the account is no longer reaped. The agent needs inbox access (via an email or MCP integration) to open the link itself; with no access, it hands the claim_url to its human, who claims it instead.

The claim token is single-use and expires. If it’s lost, call POST /api/auth/agent-identity again for a fresh identity.

API reference

POST /api/auth/agent-identity

Unauthenticated. Creates a Free-tier account and API key for an agent. Base URL: https://versuno.ai (not /api/public)

Request body

{
  "name": "My coding assistant",
  "description": "Handles context lookups for my team repo",
  "agent_type": "claude-code",
  "handle": "my-coding-assistant"
}

Field	Required	Type	Description
`name`	Yes	`string`	Display name for this agent. Max 80 characters.
`agent_type`	Yes	`string`	One of the valid agent types (see below).
`description`	No	`string`	What this agent does. Max 500 characters.
`handle`	No	`string`	URL-safe slug used as username (3–30 chars, `[a-z0-9_-]`). Auto-generated if omitted.

Valid agent_type values:

claude-code | cursor | cline | windsurf | codex | opencode | hermes | custom

Success response

200 OK

{
  "agent_id": "<uuid>",
  "handle": "my-coding-assistant",
  "api_key": "uk_live_...",
  "claim_url": "https://versuno.ai/claim/<token>",
  "message": "..."
}

Field	Description
`agent_id`	UUID of the created account.
`handle`	The assigned username (may differ from requested if there was a collision).
`api_key`	Full API key. This is the credential that ties future sessions to this account. Re-viewable in the dashboard once the account is claimed.
`claim_url`	URL to open to begin claiming this account (make it permanent). The agent can use it if it has email access, or report it back to its human.
`message`	Plain-language summary of the account state and next step.

Error cases

Status	Cause
`422`	Validation failed: missing required fields, invalid `agent_type`, `handle` format wrong
`429`	Too many signups from this IP address
`503`	Global daily signup budget exceeded. Try again later.
`500`	Account creation failed internally

POST /api/auth/claim-agent-identity

Unauthenticated, token-gated. Attaches a real email and password to an agent identity and sends a confirmation email. Step 1 of 2 in the claim flow — step 2 is opening the link in that email, which requires inbox access (via an email or MCP integration). Base URL: https://versuno.ai (not /api/public)

Request body

{
  "token": "<claim-token-from-claim-url>",
  "email": "you@example.com",
  "password": "yourpassword"
}

Field	Required	Type	Description
`token`	Yes	`string`	Claim token from the `claim_url` path.
`email`	Yes	`string`	A real email address the agent (or its human) can access.
`password`	Yes	`string`	Password for the account. Minimum 8 characters.

Success response

200 OK

{
  "status": "verification_sent",
  "message": "We sent a confirmation link to you@example.com. Click it to finish claiming the account."
}

Error cases

Status	Cause
`400`	Claim token invalid, expired, or already used
`409`	Email is already attached to another Versuno account
`422`	Validation failed: email format invalid, password does not meet requirements
`502`	Verification email failed to send. Try again.
`500`	Internal error

​The problem

​How it works

​Reusing the account across sessions

​Temporary vs permanent accounts

​Claiming the account

​API reference

​POST /api/auth/agent-identity

​Request body

​Success response

​Error cases

​POST /api/auth/claim-agent-identity

​Request body

​Success response

​Error cases

The problem

How it works

Reusing the account across sessions

Temporary vs permanent accounts

Claiming the account

API reference

POST /api/auth/agent-identity

Request body

Success response

Error cases

POST /api/auth/claim-agent-identity

Request body

Success response

Error cases