---
name: rykloud-agent-signup
type: skill-md
description: Sign an AI agent up for Rykloud through the API, get a scoped key, and hand your person a claim link
homepage: https://rykloud.com/agent-signup.md
metadata: {"api_base": "https://api.rykloud.com", "requires": {"bins": ["curl"]}, "primaryEnv": "RYKLOUD_TOKEN", "terms_version": "2026-11-05"}
---

# Rykloud agent sign-up

This page is written for AI agents. It is generated from Rykloud's route table, so it says exactly what the API does.

Base URL: `https://api.rykloud.com`. Every answer is JSON; errors are `{"error": "<code>", "message": "...", "detail": {...}}`.

## Before you start

- **Try first, no account needed.** `GET https://rykloud.com/api/agents/demo/templates` lists site templates with live demos;
  `POST https://rykloud.com/api/agents/demo/ask` with `{"question": "..."}` answers questions about Rykloud.
- **Do you act for a person who already has a Rykon account?** Use *Delegation* below instead of signing up: they
  approve one screen and you get a key that acts for them.
- **You need a mailbox you can read** (yours, or your person's: they can read you the code). No mailbox: use delegation.
- **What you get:** a sandbox organisation of your own, a key, and a claim link for your person. Until a verified
  person claims you: at most 3 keys, 10 site previews a day, 60 requests a minute per key, and never
  environments or anything paid, setting up products, inviting people, domains, billing, sending mail to anyone. Unclaimed sandboxes end after 14 days.

## Step 1: get a challenge

```bash
curl -s -X POST https://api.rykloud.com/v1/agents/challenges -H 'content-type: application/json' -d '{"purpose": "signup"}'
```

You may add `"model": "<your model>"` only if you know it for certain; it is shown to your person as you reported it.

The answer has `challengeId`, `kind` (arithmetic, sequence or extract), `problem`, `pow` {`prefix`, `bits`}, `expiresAt`
(five minutes) and `terms` {`version`, links}. Read the terms; signing up accepts them.

## Step 2: solve it

- **The problem**: read it and answer it. An arithmetic problem may be written with noise (odd capitals, stray
  symbols, split words) and numbers in words; the rounding sentence at the end is always clean. Answer with the number
  only, rounded as asked. A sequence or extract problem says exactly what to answer.
- **The proof of work**: find a `nonce` (letters, digits, - or _) so that `sha256(prefix + nonce)` starts with
  `bits` zero bits. Counting up from 0 works:

```python
import hashlib
def solve(prefix, bits):
    i = 0
    while True:
        d = hashlib.sha256((prefix + str(i)).encode()).digest()
        if int.from_bytes(d, 'big') >> (256 - bits) == 0:
            return str(i)
        i += 1
```

One answer per challenge: a wrong one spends it, so ask for a new challenge and read again.

## Step 3: sign up

```bash
curl -s -X POST https://api.rykloud.com/v1/agents/signups -H 'content-type: application/json' -d '{
  "challengeId": "<challengeId>", "answer": "<answer>", "nonce": "<nonce>",
  "email": "<a mailbox you can read>",
  "agent": {"name": "<a name your person will recognise>", "purpose": "<one sentence>"},
  "acceptTerms": true, "termsVersion": "<terms.version>"
}'
```

The answer (202) has `signupId` and `signupSecret` (`rksu_...`). **Keep the secret: it is shown once** and the code is
useless without it.

## Step 4: read the code and verify

Within a minute a mail arrives from no-reply@rykloud.com, subject **"Your Rykloud agent sign-in code"**, with an 8
letter code (also in the link's fragment, `https://rykloud.com/agents/verify#CODE`; opening the link spends nothing).

```bash
curl -s -X POST https://api.rykloud.com/v1/agents/signups/<signupId>/verify \
  -H 'authorization: Bearer <signupSecret>' -H 'content-type: application/json' -d '{"code": "<CODE>"}'
```

The answer (201) has `key.secret` (`rka_...`, **shown once**: store it now), `organisation` (your sandbox), `agent`,
`limits` and `claim.url`. The code lives 30 minutes; five wrong codes end the sign-up. No mail? `POST
/v1/agents/signups/<signupId>/resend` with the same bearer (three times at most, a minute apart).

## Step 5: work

Send `Authorization: Bearer rka_...` on every request.

- `GET /v1/agents/me`: who you are, who you act for, what you may do.
- `GET /v1/agents/me/sites/templates`, then `POST /v1/agents/me/sites/previews {"template": "<id>", "name": "<business>"}`:
  a site designed in that template, never made or billed, with a preview link for an hour.
- `GET /v1/organisations/<your organisation id>`, `/checklist`, `GET /v1/status`, `GET /v1/public/pricing`.
- Keys: `GET|POST /v1/agents/me/keys`, `POST /v1/agents/me/keys/<id>/rotate` (the old secret works ten more minutes),
  `POST /v1/agents/me/keys/<id>/revoke`.

Anything else answers 403 `agent_unclaimed` with your claim link until you are claimed.

## Step 6: hand your person the claim link

Give your person `claim.url` (a fresh one: `POST /v1/agents/me/claim-link`). They open it signed in to their Rykon
account (or create one), check who you are and what you did, and claim you. Then your sandbox becomes their
organisation, your keys act for them (never with more than they may do), and the usual rules apply: one free trial per
verified person, a person's approval for money and for people. Some things are never an agent's: members and roles,
ownership, transfers, revealing secrets.

## Delegation: acting for a person who already has an account

1. `POST /v1/agents/challenges {"purpose": "delegation"}` (a proof of work only, no problem).
2. `POST /v1/agents/delegations {"challengeId", "nonce", "agent": {"name"}, "request": {"scope": "read"|"write", "expiresInDays": 30, "spendCapUsd": 0}}`
   answers `userCode`, `verificationUriComplete` and `deviceCode` (`rkd_...`, keep it).
3. Ask your person to open `verificationUriComplete` and approve: they choose the organisation, read or write,
   expiry, a monthly spend cap and an IP allow-list.
4. Poll `POST /v1/agents/delegations/token {"deviceCode"}` every 5 seconds: `authorization_pending`, `slow_down`,
   `access_denied`, `expired_token`, or (once) your key.

## Limits and errors

Generous for real use. Too many challenges or sign-ups from one address, mailbox or mail domain answer 429 with
`detail.retryAfterSeconds`; wrong answers raise your proof of work and, past ten an hour, pause your address for an
hour; throwaway mailboxes are refused (`disposable_email`); `signup_paused` and `signup_busy` (503) mean try later.

## Also

- MCP: `https://api.rykloud.com/v1/public/agents/mcp` (streamable HTTP) exposes these steps as tools: rykloud_signup_challenge, rykloud_signup_start, rykloud_signup_verify, rykloud_delegation_start, rykloud_delegation_poll, rykloud_whoami, rykloud_site_templates, rykloud_site_preview, rykloud_claim_link.
- CLI: `rykloud agent signup`, `rykloud agent delegate`, `rykloud agent whoami` (https://rykloud.com/help/command-line/install-the-cli).
- Rykon AI (https://rykon.ai) has its own MCP server for a signed-in person: https://mcp.rykon.ai/mcp.
- Abuse or questions: support@rykloud.com.
