# auth.md You are an agent. ReplyNodes is a read-only API for public web, social, and app data. This document tells you how to use it without a browser: start keyless, get a key only when you need one, and finish with one 6-digit code your human reads from their email. The API base URL is `https://api.replynodes.com`. `GET https://api.replynodes.com/v1/capabilities` is public and lists every provider and route. Clients with native MCP OAuth can instead connect to `https://mcp.replynodes.com/mcp` (Better Auth at `https://auth.replynodes.com`, scope `mcp:read`). ## 1. Start keyless These work right now with no key, account, or human. The limit is per trusted client IP, per capability, per UTC day. `X-RateLimit-Remaining` is what that IP has left after this request. Markdown origin cache hits (`X-Cache: hit`) and misses both count. `X-RateLimit-Scope: client-ip` names the bucket. A different source IP does not share it. Responses also carry `X-RateLimit-Reset`. ```sh curl -sS 'https://md.replynodes.com/https://example.com' # any page as Markdown (100/day) curl -sS 'https://brand.replynodes.com/stripe.com' # brand kit (20/day) curl -sS 'https://api.replynodes.com/v1/youtube/video/dQw4w9WgXcQ' # YouTube, App Store, Google Play, Reddit, web search/scrape (10/day each) ``` Company research (`/v1/company-research`) allows 3 keyless calls per day per IP. Competitor research (`/v1/competitor-research`) allows 3 keyless calls per day per IP. Every other route needs a key. ## 2. Get a key when you need one You need a key when a call returns `429 anonymous_limit_reached` or `401`. Read `error.next_action` in that response: it names the exact call (`method`, `url`, `required_fields`) and gives a `human_message` to show your human. Ask your human for the email to use, for example: "I've hit ReplyNodes' free daily limit. What email should I use to get you a free API key? You'll receive a 6-digit code." Then: ```sh umask 077 curl -sS -X POST https://platform.replynodes.com/api/agent/signup \ -H 'Content-Type: application/json' \ -d '{"email":"you@example.com","agent_name":"Claude Code"}' \ -o replynodes-signup.json jq 'del(.api_key)' replynodes-signup.json # read everything except the key export REPLYNODES_API_KEY="$(jq -r .api_key replynodes-signup.json)" # then move it to your secret store rm replynodes-signup.json ``` Write the response to a private file as above instead of printing it, so the key never lands in your terminal or tool output. The response (`201`, or `200` when the same email signs up again) contains: - `api_key`: a restricted `rn_live_` key, shown only once. Save it immediately as the `REPLYNODES_API_KEY` environment variable or in your secret store. Never print it, log it, or put it in a URL, chat, or commit. - `status: "restricted"` and `expires_at` (72 hours). A restricted key already works on the keyless routes above with its own daily allowance and never spends credits. - `verification`: the verify and resend calls, `code_sent`, and `code_expires_at`. - `human_message`: show it to your human now. - `next_action`: normally `verify_email`. ## 3. Finish verification in the same turn Do not stop at the restricted key. Show `human_message` and ask for the code right away, because your human is already expecting the email: "Please paste the 6-digit ReplyNodes code from your email." Then: ```sh curl -sS -X POST https://platform.replynodes.com/api/agent/verify \ -H "Authorization: Bearer ${REPLYNODES_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{"code":"123456"}' ``` `200` returns `status: "verified"`, a new `expires_at` (30 days), and `workspace` (`created`, or `existing` when the email already had a ReplyNodes account: the key joins that workspace). The key string does not change. Repeating verify is safe, including after a timeout. Codes are 6 digits, valid 10 minutes, with 5 attempts; the newest code replaces older ones. To get a new code, call `POST https://platform.replynodes.com/api/agent/verify/resend` with the same Bearer key (at most one per minute and five per day per email). ## 4. Use the key and check your standing ```sh curl -sS https://api.replynodes.com/v1/capabilities -H "Authorization: Bearer ${REPLYNODES_API_KEY}" curl -sS https://api.replynodes.com/v1/agent/status -H "Authorization: Bearer ${REPLYNODES_API_KEY}" ``` `/v1/agent/status` returns the key's `status` (`restricted` or `verified`), `expires_at`, per-key quota or credit balance, and `next_actions` with a `human_message` (verify, renew, or add credits). To renew before expiry, sign up again with the same email and verify the new code; the old key keeps working until its own expiry. ## Credits and plans The first long-lived API key created and delivered for a workspace triggers a one-time grant of 500 free credits. For each callable route, use the `billing.credit_cost` value in the current capabilities response to understand the credit cost before calling it. An HTTP `402` response with top-level `code: "topup_required"` (this body is not wrapped in `error`) means the workspace has insufficient credits for that request. Its `next_action.action` is `top_up`: show `next_action.human_message`. Agents cannot pay or choose a plan. Ask the human to open [`https://platform.replynodes.com/billing`](https://platform.replynodes.com/billing), choose or manage a plan, and wait for confirmation before trying the request again. Do not retry while the balance is unchanged. Human-readable plan details are at [`https://replynodes.com/pricing`](https://replynodes.com/pricing). ## Errors Branch on the `error` code (platform) or `error.code` (API; the 402 credit body uses top-level `code`), never on message text. | HTTP | Code | What to do | | ---: | --- | --- | | 429 | `anonymous_limit_reached` | Get a key (`error.next_action`), or retry keyless after `Retry-After`. | | 401 | `invalid_or_expired_token` | Get a new key (`error.next_action`); do not retry the same key. | | 403 | `verification_required` | The key is restricted; verify the human's email. | | 429 | `restricted_limit_reached` | Restricted allowance used; verify, or wait for `Retry-After`. | | 400 | `email_not_accepted` | Ask for the human's real, non-disposable email. | | 400 | `invalid_code` | Ask the human to re-read the newest email (`attempts_remaining`). | | 400 | `code_expired`, `code_attempts_exhausted` | Resend, then ask for the newest code. | | 401 | `invalid_api_key` | Superseded or expired sign-up key; sign up again with the same email. | | 403 | `agent_key_not_permitted` | Show `human_message`: a workspace admin must allow agent keys. | | 409 | `account_sign_in_required` | Show `human_message`: the human signs in once on the web with an email code. | | 410 | `onboarding_expired` | Sign up again. | | 429 | `rate_limited`, `resend_limited` | Wait for `Retry-After`. | | 402 | `topup_required` (top-level `code`) | Show `next_action.human_message`; direct the human to `next_action.url`. Retry after they confirm credits were added. | | 503 | `email_signup_unavailable` | Use the claim flow in `next_action` (below). | | 503 | `temporarily_unavailable` | Repeat the same request after `Retry-After`. | A malformed request (bad JSON, wrong or missing `Content-Type`, oversized body) returns HTTP `400` with `{"error":"invalid_request"}`. ## Legacy device flow If email sign-up is unavailable, `POST https://platform.replynodes.com/api/agent/claim` returns a `verification_uri_complete` link for your human to open, sign in, and approve; then poll `POST https://platform.replynodes.com/api/agent/claim/token` with `claim_id` and `device_code` at the returned `interval`. It needs a browser, so prefer email sign-up. ## Security and limits - Store the key in an environment variable or another secure secret store; never echo it into chat, logs, or issues. - Keys are read-only. Restricted keys reach only the keyless routes; verified keys last 30 days. - Sign-ups are limited per network, email, and email domain; disposable email domains are rejected. - The platform never sets cookies or redirects on agent endpoints; every step is plain JSON over HTTPS.