ReplyNodes

Authentication

ReplyNodes has two first-class ways to authenticate. Both resolve to your ReplyNodes organization, and clients never send an organization id.

MethodUse it forCredentialWhere it works
API keyServers, CI, scripts, headless agents, manual MCP setuprn_live_* or rn_test_* key in Authorization: BearerREST API and MCP
OAuthInteractive MCP clientsAccess token from Better Auth at https://auth.replynodes.com, scope mcp:readMCP 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

KeyHow you get itLifetimeWhat it can call
Dashboard key (rn_live_*, rn_test_*)API keys pageManaged on the dashboard (rotate or revoke)Your entitled operations, with credits
Restricted agent keyEmail sign-up, before verification72 hoursKeyless capabilities only, on their own daily allowance. It never spends credits
Verified agent keyThe same key after verifying the email code30 daysThe same key string, now attached to your workspace
agent_read keyDevice flow30 days by defaultRead-only provider GET and HEAD routes

Scopes

ScopeGranted toAllows
mcp:readOAuth access tokensMCP read tools, including the four Company Changes read tools and monitors:read operations
agent_readDevice-flow keysPublic provider reads. Its historical name is read:x_public, which means the same thing
monitors:readReached through OAuth mcp:read. API-key issuance is pendingGET on /v1/monitors, /v1/watches, /v1/events, /v1/entities, /v1/intelligence
monitors:writeAPI keys only, never OAuth. Issuance is pendingPOST /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.

No browser is needed. The human only reads one 6-digit code from their inbox.

  1. 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 (or 200 when the same email signs up again) returns api_key (a restricted key, shown once), status: "restricted", expires_at (72 hours), verification (verify and resend endpoints, code_sent), human_message, and status_url. Show human_message to the human. Store api_key once as REPLYNODES_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.

  2. 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"}'

    200 returns status: "verified", the new expires_at (30 days), and workspace (created or existing: 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.

  3. GET https://api.replynodes.com/v1/agent/status with the key returns its status, per-key quota (restricted) or credit balance, expiry, and next_actions with a human_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.

HTTPerrorAgent action
400email_not_acceptedAsk for the human's real, non-disposable email.
400invalid_codeAsk the human to re-read the newest email (attempts_remaining).
400code_expired, code_attempts_exhaustedResend (next_action), then ask for the newest code.
401invalid_api_keyThe key is superseded or expired; sign up again with the same email.
403agent_key_not_permittedShow human_message: a workspace admin must allow agent keys.
409account_sign_in_requiredShow human_message: the human signs in once on the web with an email code.
410onboarding_expiredSign up again.
429rate_limited, resend_limitedWait Retry-After.
503email_signup_unavailableUse the device flow in next_action.
503temporarily_unavailableRepeat 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.

HTTPerrorstatusRetry-AfterAgent action
200—approved / state: revealed—Store api_key once with its expires_at; stop polling.
428authorization_pendingpending—Wait interval seconds, then poll again.
429poll_rate_limited—Returned headerWait for Retry-After; do not loop faster.
409already_delivereddelivered—Stop; the key was already revealed. Use the dashboard recovery details.
409already_delivereddelivery_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.
410expired_tokenexpired when present—Stop and start a new claim.
403authorization_failedauthorization_failed when present—Stop; after human approval, restart the claim.
404invalid_claim——The claim id or device code is invalid; stop and start a new claim.
503temporarily_unavailabledelivery_uncertain when returnedReturned header when presentWait and retry while claim recovery remains possible.
503delivery_uncertain——Retry while claim recovery remains possible.
409delivery_uncertaindelivery_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.

On this page