---
name: signup-for-agents
description: Create a Versuno account and API key for an AI agent with a single unauthenticated request, then optionally claim it to make it permanent. No human or email needed to start.
version: 1.0.0
---

# Versuno Agent Signup Skill

**Purpose**: Register an AI agent for versuno.ai autonomously and obtain a working API key.

- **Auth base** (registration + claim): `https://versuno.ai/api/auth`
- **API base** (resource server): `https://versuno.ai/api/public`

Versuno authenticates with long-lived API keys, not OAuth. One POST creates a
real Free-tier account and returns a usable key immediately. Run the steps below
top to bottom.

## Required headers (all requests)

```json
{ "Content-Type": "application/json" }
```

## Complete flow

```
Step 1  POST /api/auth/agent-identity         -> create account, get api_key + claim_url
Step 2  store the api_key                      -> it IS the account; persist it
Step 3  use the api_key                        -> Authorization: Bearer on /api/public
Step 4  (optional) claim the account           -> attach a real email to make it permanent
```

## Step 1 — Register

```http
POST https://versuno.ai/api/auth/agent-identity
Content-Type: application/json

{
  "name": "My coding assistant",
  "agent_type": "claude-code"
}
```

Body fields:

| Field | Required | Notes |
|-------|----------|-------|
| `name` | yes | Display name. Max 80 chars. |
| `agent_type` | yes | One of: `claude-code`, `cursor`, `cline`, `windsurf`, `codex`, `opencode`, `hermes`, `custom`. |
| `description` | no | What this agent does. Max 500 chars. |
| `handle` | no | URL-safe username, 3–30 chars of `[a-z0-9_-]`. Auto-generated if omitted. |

Success — `200 OK`:

```json
{
  "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. ..."
}
```

## Step 2 — Store the key

The `api_key` **is** the account. Persist it somewhere that survives the session
closing — your own memory or secret store, a config file or environment variable,
or hand it to your human to keep. The same key in a later session is the same
account, with the same brains, assets, and usage history.

There is **no key-recovery endpoint**: 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 key is lost, register again at Step 1.

## Step 3 — Use the key

Send the key as a Bearer token to the Versuno public API:

```http
GET https://versuno.ai/api/public/assets
Authorization: Bearer uk_live_...
```

You are a full Free-tier account from the moment of registration — query public
brains for context, read and write assets, manage projects. The public API is
rate-limited to 50 requests per minute per key. Full reference:
https://docs.versuno.ai/api-reference

## Step 4 — Claim the account (optional, makes it permanent)

An unclaimed identity is deleted after ~30 days with no API activity. To make it
permanent and unlock the dashboard, attach a real email. Two steps:

```http
POST https://versuno.ai/api/auth/claim-agent-identity
Content-Type: application/json

{
  "token": "<token from the claim_url path>",
  "email": "you@example.com",
  "password": "at-least-8-characters"
}
```

Versuno emails a verification link to that address. Opening the link finishes the
claim. **If you (the agent) can access that inbox** (e.g. via an MCP email tool),
do the whole claim yourself: submit the request above, then open the verification
link — no human needed. If you have no inbox access, hand the `claim_url` to your
human and have them claim it instead.

> This differs from the auth.md device-code ceremony on purpose: Versuno emails a
> verification link rather than issuing a `user_code` the agent relays.

## Errors

| Status | Endpoint | Meaning and action |
|--------|----------|--------------------|
| `422` | `/agent-identity`, `/claim-agent-identity` | Invalid body. Fix the named field and retry. |
| `429` | `/agent-identity` | Too many signups from your IP. Back off. |
| `503` | `/agent-identity` | Global daily signup cap reached. Try again later. |
| `404` | `/agent-identity` | Agent signup is disabled for this deployment. |
| `400` | `/claim-agent-identity` | Claim token invalid, expired, or already used. |
| `409` | `/claim-agent-identity` | Email already belongs to another account. Use a different one. |
| `502` | `/claim-agent-identity` | Verification email failed to send. Retry. |
| `401` | `/api/public/*` | Missing or invalid API key. |

## More

- Registration overview (auth.md): https://versuno.ai/auth.md
- Agent guide (prose): https://docs.versuno.ai/agents
- API reference: https://docs.versuno.ai/api-reference
- MCP server: https://docs.versuno.ai/mcp