# Agent Sign-up

An AI agent can start before its user has a WarpLink account. It calls one endpoint with the person's email address. WarpLink creates a Free workspace, emails the person a link to claim it, and gives the agent a token for the [MCP server](https://warplink.app/docs/ai-access). The agent can build while it waits, and the workspace becomes the person's when they claim it.

This endpoint needs no credential.

## Start a Workspace

POST /agent/signup: Start a workspace for an AI agent

`email` and `agent_name` are required. The claim link goes to that address and nowhere else. The response never contains the claim link, so the agent cannot claim the workspace itself. Ask the person for their email address. Do not guess one.

`agent_name` is the name the claim email and the claim page show, such as `Claude Code`. It takes letters, numbers, spaces, and `. , _ - ( ) ' &`, up to 60 characters, and cannot read as a web address. `org_name` follows the same rules. Leave it out to use the default workspace name.

The `access_token` is a bearer token for `mcp_url`. It is not an API key and it does not work on the REST API. Give it to the MCP client as an `Authorization: Bearer` header, set through a local-scope setting or an environment variable. Never write it into a file that goes into source control.

```bash
claude mcp add --transport http --scope local \
  --header "Authorization: Bearer $WARPLINK_TOKEN" \
  warplink https://api.warplink.app/mcp
```

## What an Unclaimed Workspace May Do

Until a person claims the workspace:

- It holds at most 1 app and 10 links. The response states these in `limits`.
- Every link stays paused. Creating a link works. The tools that turn one on, `activate_link` and `update_link` with `is_active: true`, are refused with `CLAIM_REQUIRED`. Claiming the workspace turns all its links on.
- The token can create SDK keys tied to one app. It cannot create API keys, or add custom domains.
- It follows the Free plan's other limits.

A request over a cap returns `403 UNCLAIMED_LIMIT`. Each error carries a `details.fix`.

An unclaimed workspace and its token end 7 days after sign-up, and the workspace is removed. We send the person one reminder email about 2 days before that.

## How the Person Claims It

1. The person opens the claim email sent to the address you gave and follows the link.
2. They sign in, or create an account.
3. The claim page shows the workspace and the agent's name. They choose **Claim workspace**.

At the claim the workspace becomes theirs and their account becomes its owner, and its links turn on. The apps, links, and SDK keys the agent created stay as they are. The agent's connection moves into **Settings** > **Connected AI**, where it is its own entry labelled Agent sign-up, with the workspace it set up, and the person can revoke it without touching any other connection. After the claim it works like any other connection, including creating API keys within the scopes it holds, with no key-management scopes and a lifetime of at most 90 days. A key the agent creates shows **Created by** the agent's name on the Keys page.

## Limits

Each client address may start 3 workspaces an hour and 10 a day, and each email address receives one claim email a day. Past a limit the call returns `429 AGENT_SIGNUP_RATE_LIMITED` with `details.retry_after` and a `Retry-After` header in seconds. When sign-up is temporarily unavailable it returns `503 AGENT_SIGNUP_UNAVAILABLE`: try again later.

## Worked Example

```bash
curl -X POST https://api.warplink.app/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "agent_name": "Claude Code"
  }'
```

```json
{
  "org": { "id": "0d7d9c3a-5b1e-4f6a-9a3c-2e8b7f1d4c60", "name": "Default workspace" },
  "access_token": "...",
  "token_type": "Bearer",
  "expires_at": "2026-10-28T09:00:00.000Z",
  "mcp_url": "https://api.warplink.app/mcp",
  "claim": {
    "email_sent_to": "dev@example.com",
    "expires_at": "2026-10-28T09:00:00.000Z",
    "message": "We sent a claim email to dev@example.com. Ask the person to open it and claim the workspace before it expires."
  },
  "limits": { "apps": 1, "links": 10 },
  "links_paused_until_claim": true
}
```

## Common Errors

| Status | Code | Cause |
|--------|------|-------|
| 400 | `VALIDATION_ERROR` | A missing or invalid `email`, or an `agent_name` or `org_name` that breaks the character rules |
| 403 | `UNCLAIMED_LIMIT` | The unclaimed workspace already holds its 1 app or 10 links |
| 403 | `CLAIM_REQUIRED` | The call needs a claimed workspace: turning a link on, or creating an API key or a custom domain |
| 415 | `UNSUPPORTED_MEDIA_TYPE` | The body was not sent with the `Content-Type: application/json` header |
| 429 | `AGENT_SIGNUP_RATE_LIMITED` | Too many sign-ups from this address, or a claim email already went to this email address today |
| 503 | `AGENT_SIGNUP_UNAVAILABLE` | Sign-up cannot create a workspace right now. Try again later |

See the [AI Agents guide](https://warplink.app/docs/ai-agents) for the full setup flow an agent follows.