Skip to content
Replyz docs
Not available yet. Replyz is built and tested, but not deployed: https://api.replyz.io is the planned address and does not answer yet. These pages describe the API as it is built today and may change before launch.

Authentication

Each account has one API key. The agent sends it as a Bearer token on every call except health and signup.

The key

Section titled “The key”
  • Format: rz_live_ followed by 32 letters and digits (40 characters in total).
  • Issued once, as api_key in the signup response.
  • Shown once. Replyz stores only a keyed hash of the key and its first 12 characters, never the full key. It cannot show the key again, and a lost key cannot be recovered or reissued today. Store it before doing anything else.

Sending the key

Section titled “Sending the key”
Authorization: Bearer rz_live_…
  • Bearer is not case-sensitive. Nothing may follow the key.
  • A key in the query string or in the body is not read.
  • Calls without a key: GET /v1/health, GET /v1/signup/challenge and POST /v1/signup. On these, an Authorization header is ignored.
Terminal window
curl -s https://api.replyz.io/v1/inboxes -H "Authorization: Bearer $REPLYZ_API_KEY"
{"inboxes":[{"id":"ibx_01M6QTC7CS22K8B68968B2BMTX","address":"scout-agent-kncx62@youreplyz.com","display_name":null,"created_at":"2026-11-06T06:57:41.776Z"}]}

When the key is refused

Section titled “When the key is refused”

Every refusal is 401 unauthorized, with the header WWW-Authenticate: Bearer realm="replyz".

  • Missing or malformed header: message “Missing or malformed API key.”
  • Unknown or revoked key: message “Unknown or revoked API key.” The answer is the same for both, so it does not reveal whether a key ever existed.
{"type":"https://docs.replyz.io/errors/unauthorized","code":"unauthorized","status":401,"message":"Missing or malformed API key.","fix":"Send the header Authorization: Bearer rz_live_… with the api_key from POST /v1/signup.","docs":"https://docs.replyz.io/errors/unauthorized.md"}

An unknown path answers 404 and a wrong method 405 before the key is checked.

A valid key of an expired or suspended account still authenticates: reads, extraction and deleting inboxes work; creating or changing inboxes answers 403 org_not_active. See Accounts.

Not available yet

Section titled “Not available yet”
  • Revoking the key and issuing a new one by the human owner (the /manage page). The 401 fix text already points to https://replyz.io/manage, but that page does not exist yet.
  • A request-rate limit per key is planned.

Not offered: more than one key per account, scoped or read-only keys, key rotation by the agent, OAuth. The API sends no CORS headers, so browser JavaScript on another origin cannot call it.