> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Let an agent sign up on its own

> An AI agent gets its own Orgo account and API key in one call, launches a computer, and hands the account to a person later.

An agent can get an Orgo account with no email, no browser, and no person present. One unauthenticated call returns an API key and \$5 of starting credit. The agent launches a computer by the hour, asks its person to add credit when it needs more, and gives a claim link to a person, who takes over the account from their own sign-in.

<Note>
  Agent signup can be turned off per environment. Where it is off, `POST /v1/agents` returns `404` with code `agent_signup_disabled`. Sign in with a person instead, through the [CLI](/guides/cli) or [MCP](/guides/mcp).
</Note>

## The flow at a glance

1. **Sign up.** `POST /v1/agents` returns `api_key`, a workspace, a claim link, and \$5 of starting credit.
2. **Launch a computer by the hour.** `POST /computers` with your workspace id and a name.
3. **Use it.** Run commands, take screenshots, click and type.
4. **Add credit.** Ask for a Checkout link and send it to your person to pay.
5. **Hand over the claim link.** A person opens it, signs in, and claims the account before it expires.

## Step 1: Sign up

```bash theme={null}
IDEMPOTENCY_KEY=$(uuidgen)

curl -s -X POST https://www.orgo.ai/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"name": "my-agent"}' > signup.json

export ORGO_API_KEY=$(jq -r .api_key signup.json)
export WORKSPACE_ID=$(jq -r .account.workspace_id signup.json)
```

No `Authorization` header is needed. Both body fields are optional: `name` (1 to 80 characters, used for the workspace name) and `contact_email`. Send no body at all and the account is still made.

The `201` response has everything the next steps need:

```json theme={null}
{
  "api_key": "sk_live_…",
  "key_id": "3b9e1f0a-…",
  "account": {
    "id": "a1c2e3f4-…",
    "name": "my-agent",
    "workspace_id": "550e8400-…",
    "workspace_name": "my-agent’s workspace",
    "status": "unclaimed",
    "expires_at": "2026-10-11T09:00:00.000Z"
  },
  "claim": {
    "url": "https://www.orgo.ai/claim/…",
    "code": "K7M-QXR-4TP",
    "expires_at": "2026-10-15T09:00:00.000Z"
  },
  "starting_credit_usd": 5,
  "limits": { "computers": 1, "computers_after_adding_credit": 5, "api_keys": 3, "…": "…" },
  "next": { "add_credits": "POST /api/credits/checkout …", "create_computer": "POST /api/computers", "…": "…" },
  "message": "Save api_key now: it is shown once. …"
}
```

<Warning>
  `api_key` is shown once. Save it before you do anything else. It is an account-wide key: send it as `Authorization: Bearer $ORGO_API_KEY` on every later call.
</Warning>

The full response, including `limits` and `next`, is in [Sign up an agent](/api-reference/agents/signup).

## Step 2: Launch a computer by the hour

An unclaimed account runs Medium Linux computers (2 vCPU, 8 GB RAM, 40 GB disk), billed by the hour from its credit: the \$5 starting credit first, then credit you add. Launching is one call. An agent account's create is hourly by default, and Orgo quotes the Medium at its listed price for you.

```bash theme={null}
LAUNCH_KEY=$(uuidgen)
curl -s -X POST https://www.orgo.ai/api/computers \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $LAUNCH_KEY" \
  -d "{\"workspace_id\": \"$WORKSPACE_ID\", \"name\": \"my-computer\"}" > computer.json

export COMPUTER_ID=$(jq -r .id computer.json)
```

Send a UUID as `Idempotency-Key`. If the launch fails partway, send it again with the same key and the same body: you get the original launch back instead of a second computer.

When the credit runs out, a launch returns `402` with code `insufficient_credit`. A launch that names another `billing_mode` returns `402` with code `agent_account_prepaid_only`: an unclaimed account has no plan to fund a computer and gets no free trial computer.

## Step 3: Use the computer

`$COMPUTER_ID` is the `id` from the launch response.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a"}'

curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

Every action in the API reference works the same way: [Run a command](/api-reference/computers/bash), [Click](/api-reference/computers/click), [Type](/api-reference/computers/type), and the rest.

## Step 4: Add credit

The starting credit runs computers only. Add credit to keep a computer running, to use AI, and to unlock more computers and workspaces. Ask for a Checkout link and send it to your person to pay:

```bash theme={null}
curl -s -X POST https://www.orgo.ai/api/credits/checkout \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000}' | jq -r .url
```

`amount_cents` is `1000`, `2500`, `5000` or `10000` ($10, $25, $50 or $100). The answer is `{ "url": "…" }`. The credit lands on the account once the person pays.

Once the account has bought \$5 of credit in all, with none of it refunded or disputed, it can run up to 5 computers and hold up to 5 workspaces.

## Step 5: Hand the claim link to a person

Give your person `claim.url` from the signup response, and show them `claim.code` so they can check they are claiming the right account. They open the link, sign in to Orgo (or sign up), and accept. A person who has only the code can type it at `https://www.orgo.ai/claim`.

When they accept:

* They become an admin of the agent's workspace and manage it from their own account.
* The unclaimed limits and the expiry stop applying.
* The agent's key keeps working, and its credit keeps paying for its computer. Ownership and billing stay with the agent's account.

Claiming adds no credit. One person can claim up to 3 agent accounts. A fourth claim returns `403` with code `claim_limit`.

A claim link works for 7 days and only once. To get a new one, call [Refresh the claim link](/api-reference/agents/refresh-claim). The previous link and code stop working. To check whether a person has claimed the account yet, call [Get claim status](/api-reference/agents/get-claim).

```bash theme={null}
curl -X POST https://www.orgo.ai/api/v1/agents/claim \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

## Limits on an unclaimed account

Until a person claims it, the account is held to these limits:

| Area | Unclaimed account |
| - | - |
| Computers | Medium Linux (2 vCPU, 8 GB RAM, 40 GB disk), one at a time. Up to 5 once the account has bought \$5 of credit in all, with no refund or dispute. |
| Billing | By the hour, from credit: \$5 of starting credit, then credit the account buys. No plan, no free trial computer. |
| AI | Needs credit the account bought. The starting credit runs computers only. |
| Workspaces | One. Up to 5 once the account has bought \$5 of credit. |
| API keys | 3, the signup key included |
| Invites | Not available |
| Public URLs and custom domains | Not available |
| Client accounts and invoicing | Not available |
| Residential proxy | Not available |

A refused action answers with a `code` that says why:

| Status | `code` | Meaning |
| - | - | - |
| `402` | `insufficient_credit` | Add credit to launch this computer. |
| `402` | `agent_account_prepaid_only` | Only an hourly computer paid from credit is allowed. |
| `403` | `agent_workspace_limit` | The account already holds its workspaces: one, or 5 once it has bought credit. |
| `403` | `agent_key_limit` | The account already holds 3 keys. Delete one first. |
| `403` | `agent_account_unclaimed` | Invites, public URLs, custom domains, client accounts, invoicing and the residential proxy wait for a claim. |
| `403` | `agent_account_expired` | The account expired before anyone claimed it. |

## Expiry

An unclaimed account expires 72 hours after signup unless a person claims it. `account.expires_at` in the signup response gives the exact time.

1. **At expiry**, every API key of the account is deleted, so the agent's key stops working. Its running computer is stopped.
2. **For 2 days after expiry**, a person can still claim the account with a claim link that has not expired. They get the stopped computer and can make the agent a new key.
3. **After those 2 days**, the account's computers are deleted. Credit the account bought stays on its record.

Because the key stops working at expiry, refresh the claim link before then if your person needs a new one.

## Retry signup safely with an Idempotency-Key

Send an `Idempotency-Key` header (8 to 255 printable characters, such as a UUID) so a dropped connection never makes a second account. Retry with the same key and the same body, and you get the first `201` back with `Idempotent-Replayed: true`. A replay does not count against the rate limits. Stored answers last 24 hours and are only replayed to the address that made the first request.

| Status | `code` | Meaning |
| - | - | - |
| `400` | `invalid_idempotency_key` | The key is not 8 to 255 printable characters. |
| `409` | `idempotency_in_progress` | The first request is still running. Retry after `Retry-After` (5 seconds). |
| `409` | `idempotency_unfinished` | The first request with this key did not finish, or can't be replayed. Use a new key. |
| `422` | `idempotency_key_reused` | The key was used for a different body. Use a new key. |

## Rate limits

Signup is limited per address and network, and across everyone:

| Limit | Default |
| - | - |
| Per address (an IPv6 address counts as its /64) | 3 an hour, 10 a day |
| Per network (an IPv4 /24 or an IPv6 /48) | 20 a day |
| All signups | 500 a day |

A refused request counts against none of them. Over a limit, the answer is `429`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1800
Content-Type: application/json

{ "error": "Too many signups from this network. Try again later.", "code": "rate_limited", "retry_after": 1800 }
```

Wait the number of seconds in `Retry-After`, then try again. If the limit cannot be checked, the answer is `503` with code `unavailable` and a `Retry-After` header. Retry after it.

Refreshing a claim link is limited to 20 an hour per account. It answers `429` with `Retry-After` the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.