Authentication
ReplyNodes has two first-class ways to authenticate. Both resolve to your ReplyNodes organization, and clients never send an organization id.
| Method | Use it for | Credential | Where it works |
|---|---|---|---|
| API key | Servers, CI, scripts, headless agents, manual MCP setup | rn_live_* or rn_test_* key in Authorization: Bearer | REST API and MCP |
| OAuth | Interactive MCP clients | Access token from Better Auth at https://auth.replynodes.com, scope mcp:read | MCP only |
Some capabilities also work with no credential. See Limits and pricing for the keyless list.
Use an API key
Create and manage keys on the API keys page. Sign in first at the dashboard. Store the key in a secret store and send it as a Bearer credential:
curl -sS \
-H "Authorization: Bearer ${REPLYNODES_API_KEY}" \
"https://api.replynodes.com/v1/capabilities"The canonical OpenAPI document defines HTTP Bearer authentication. Documented key formats are rn_test_<64hex> and rn_live_<64hex>. Never place a real key in a URL, browser bundle, prompt, log or repository. The contract accepts both prefixes; this page does not describe any difference between test and live keys.
The gateway CLI reads FETCHER_API_KEY and builds the same header. Every other client in these docs uses REPLYNODES_API_KEY; both names hold the same kind of ReplyNodes API key. Other clients should use their own secret store and follow the same HTTP header contract.
Key types
| Key | How you get it | Lifetime | What it can call |
|---|---|---|---|
Dashboard key (rn_live_*, rn_test_*) | API keys page | Managed on the dashboard (rotate or revoke) | Your entitled operations, with credits |
| Restricted agent key | Email sign-up, before verification | 72 hours | Keyless capabilities only, on their own daily allowance. It never spends credits |
| Verified agent key | The same key after verifying the email code | 30 days | The same key string, now attached to your workspace |
agent_read key | Device flow | 30 days by default | Read-only provider GET and HEAD routes |
Scopes
| Scope | Granted to | Allows |
|---|---|---|
mcp:read | OAuth access tokens | MCP read tools, including the four Company Changes read tools and monitors:read operations |
agent_read | Device-flow keys | Public provider reads. Its historical name is read:x_public, which means the same thing |
monitors:read | Reached through OAuth mcp:read. API-key issuance is pending | GET on /v1/monitors, /v1/watches, /v1/events, /v1/entities, /v1/intelligence |
monitors:write | API keys only, never OAuth. Issuance is pending | POST /v1/watches, PATCH /v1/watches/{id}, monitor create and update |
A request without the required scope returns 403 forbidden_scope. Until issuance of the monitor scopes for API keys ships, API-key monitor calls return 403 forbidden_scope. Check /v1/capabilities for the current contract.
OAuth for MCP
An MCP client that supports OAuth starts the flow from the server URL https://mcp.replynodes.com/mcp. Better Auth at https://auth.replynodes.com is the authority and the scope is mcp:read. The client handles the browser redirect and PKCE, so never copy an access token into configuration or prompts. Do not send an organization id: ReplyNodes resolves the organization from the signed-in identity. See MCP for client setup.
Rotate and revoke keys
- Dashboard keys. The API keys page has Rotate and Revoke actions, each with a confirmation step. Rotate to get a replacement key, then update your secret store. Revoke if a key may have leaked.
- Agent keys. Renew before expiry by signing up again with the same email and verifying the new code. A superseded or expired key returns
401 invalid_api_key. - If a key leaks. Revoke it right away, create a new one, and check your logs for the exposure. Keep keys out of source control and use your platform's secret scanning.
Agents
Start keyless: the capabilities in the Agent quickstart work without a key up to their daily limits. Get a key only when a call returns 429 anonymous_limit_reached or 401. That response's error.next_action names the exact call (method, url, required_fields), a human_message for the human, and retry_after_seconds. The full protocol is at https://replynodes.com/auth.md.
Email sign-up (recommended)
No browser is needed. The human only reads one 6-digit code from their inbox.
-
Ask the human which email to use, then sign up. The response is immediate:
curl -sS -X POST https://platform.replynodes.com/api/agent/signup \ -H 'Content-Type: application/json' \ -d '{"email":"you@example.com","agent_name":"my-agent","source":"docs"}'201(or200when the same email signs up again) returnsapi_key(a restricted key, shown once),status: "restricted",expires_at(72 hours),verification(verify and resend endpoints,code_sent),human_message, andstatus_url. Showhuman_messageto the human. Storeapi_keyonce asREPLYNODES_API_KEY, and never print or log it. A restricted key already calls the keyless capabilities on its own daily allowance and never spends credits. -
When the human pastes the code, verify with the same key:
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"}'200returnsstatus: "verified", the newexpires_at(30 days), andworkspace(createdorexisting: an email that already has an account attaches to that workspace). The key string does not change. Repeating verify is safe, including after a timeout. -
GET https://api.replynodes.com/v1/agent/statuswith the key returns its status, per-key quota (restricted) or credit balance, expiry, andnext_actionswith ahuman_message(verify, renew, add credits).
Codes are 6 digits, valid 10 minutes, with 5 attempts. The newest code replaces older ones. Resend with POST https://platform.replynodes.com/api/agent/verify/resend and the same Bearer key (resends are rate-limited per email).
When the workspace runs out of credits, credit-metered calls return HTTP 402 with code: "topup_required" and next_action.action: "top_up". Show its human_message: only the human can add credits, on the billing page in next_action.url. Retry once they confirm, and do not retry in a loop.
| HTTP | error | Agent action |
|---|---|---|
| 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 (next_action), then ask for the newest code. |
| 401 | invalid_api_key | The key is superseded or expired; 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 Retry-After. |
| 503 | email_signup_unavailable | Use the device flow in next_action. |
| 503 | temporarily_unavailable | Repeat the same request after Retry-After. |
On the API, a restricted key outside the keyless capabilities gets 403 verification_required, and a used-up per-key allowance gets 429 restricted_limit_reached. Both carry next_action: verify_email.
Legacy device flow
Agents can still obtain a read-only API key through a short claim approved once by a human in a browser. Start a claim with:
curl -sS -X POST https://platform.replynodes.com/api/agent/claim \
-H 'Content-Type: application/json' \
-d '{"agent_name":"my-agent","agent_platform":"my-platform","source":"docs"}'agent_name and agent_platform are optional labels. source is an optional attribution label: send "source":"anonymous_limit" when you start the claim because a request returned 429 anonymous_limit_reached (other values: skill, docs, mcp, cli, other). A successful response contains claim_id, device_code, user_code, verification_uri, verification_uri_complete, expires_in (900 seconds, or 15 minutes), interval (3 seconds), and docs. Give the human the exact verification_uri_complete link: it already includes the user_code. Wait for that one approval, then poll at the returned interval:
curl -sS -X POST https://platform.replynodes.com/api/agent/claim/token \
-H 'Content-Type: application/json' \
-d "{\"claim_id\":\"${CLAIM_ID}\",\"device_code\":\"${DEVICE_CODE}\"}"On 200, store api_key once as REPLYNODES_API_KEY, and never log it or ask the token endpoint for it again. The returned expires_at is authoritative. The default issued agent_read key lifetime is 30 days. If a later API call returns 401, start a new claim.
An agent key reaches only read-only provider GET and HEAD routes, /v1/capabilities, and the provider /v1/x surface where that surface is covered by provider-read routing. It cannot use non-GET methods or key, dashboard, internal, billing, wallet, checkout, webhooks, usage, overview, or me routes. Check /v1/capabilities for the current provider contract; this page does not promise any route outside that allowlist.
Token polling outcomes
In this table, a — in the status column means the response body has no status field on that path.
| HTTP | error | status | Retry-After | Agent action |
|---|---|---|---|---|
| 200 | — | approved / state: revealed | — | Store api_key once with its expires_at; stop polling. |
| 428 | authorization_pending | pending | — | Wait interval seconds, then poll again. |
| 429 | poll_rate_limited | — | Returned header | Wait for Retry-After; do not loop faster. |
| 409 | already_delivered | delivered | — | Stop; the key was already revealed. Use the dashboard recovery details. |
| 409 | already_delivered | delivery_uncertain | — | Do not start a new claim blindly. Check with the human on the Agent keys page, then start a new claim if the key was not stored. |
| 410 | expired_token | expired when present | — | Stop and start a new claim. |
| 403 | authorization_failed | authorization_failed when present | — | Stop; after human approval, restart the claim. |
| 404 | invalid_claim | — | — | The claim id or device code is invalid; stop and start a new claim. |
| 503 | temporarily_unavailable | delivery_uncertain when returned | Returned header when present | Wait and retry while claim recovery remains possible. |
| 503 | delivery_uncertain | — | — | Retry while claim recovery remains possible. |
| 409 | delivery_uncertain | delivery_uncertain | — | Retries are exhausted; stop and use dashboard recovery. |
The two 503 temporarily_unavailable rows differ because they belong to different endpoints. For email sign-up, repeat the same request after Retry-After. For claim polling, keep polling while recovery is still possible, and start a new claim only after the checks in the table.