Authentication

The Replyful API uses bearer-token authentication. Every request (except /health) must include an Authorization header carrying a valid API key.

Authorization: Bearer rfl_live_8c1a9f3e6b2d4a7c9e0f1a2b

Create an API key

Open the Replyful dashboard.
Navigate to Settings → Developers → API keys.
Click Create key, give it a descriptive name (e.g. “Production webhook handler”), and pick a mode and an access level.
Copy the token immediately and store it in your secret manager.

The plaintext token is shown once at creation. Replyful only stores a SHA-256 hash, so we cannot recover or display the token after the modal closes. If you lose it, archive the key and create a new one.

Key modes

Each key is created in one of two modes, identifiable from the prefix:

Prefix	Mode	When to use
`rfl_live_`	Live	Production servers acting on real data.
`rfl_test_`	Test	Development and CI. Reserved for sandbox isolation in the future. Test keys can read but cannot write yet.

Access levels

Each key has an access level, chosen when you create it:

Access	What it can do
Read only	Read tickets, contacts, attachments, channels, knowledge and help centers. The default for new keys.
Read & write	Everything a read-only key can, plus changes: creating tickets, adding messages and handing over from your own chatbot, and writing and publishing help-center articles over MCP.

Keys created before access levels existed are Read & write. Signing in to the MCP server with OAuth requires the Admin role and gives full access, the same as a Read & write key. Pick Read only unless the integration needs to change something: a leaked read-only key cannot alter your data. Every key belongs to exactly one organization. Cross-organization access is impossible by construction — a key only ever sees data from the org it was created in.

Use the key

Send the token in the Authorization header on every request, prefixed with Bearer :

curl https://api.replyful.com/v1/tickets \
  -H "Authorization: Bearer rfl_live_..."

const res = await fetch("https://api.replyful.com/v1/tickets", {
  headers: {
    Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}`,
  },
});

import os, requests

res = requests.get(
    "https://api.replyful.com/v1/tickets",
    headers={"Authorization": f"Bearer {os.environ['REPLYFUL_API_KEY']}"},
)

Security best practices

Never embed an API key in browser code, mobile apps, public repositories, or URL query strings. A leaked key gives full read access to your organization’s data, and a Read & write key can also change it, until the key is archived.

Server-side only. Call the API from your backend. Never ship a key to a browser or mobile bundle.
Use environment variables. Read the key from process.env (or your secret manager). Never hardcode it.
Header, not URL. Bearer tokens belong in the Authorization header — never in a query string, where they end up in access logs and referrer headers.
Rotate on suspicion. Keys can be archived from the dashboard. Create a new one, deploy it, then archive the old one.
One key per integration. Use separate keys for separate consumers so you can rotate or revoke them independently.

Authentication errors

Authentication failures return HTTP 401 with a consistent envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Missing Authorization header. Provide `Authorization: Bearer rfl_…`.",
    "docUrl": "https://docs.replyful.com/errors/missing_api_key",
    "requestId": "req_..."
  }
}

Code	When it fires
`missing_api_key`	The `Authorization` header is absent or does not start with `Bearer` .
`invalid_api_key`	The token is malformed (does not match `rfl_(live\|test)_...`), unknown, or has been archived.

See Errors for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

Create an API key

Key modes

Access levels

Use the key

Security best practices

Authentication errors

​Create an API key

​Key modes

​Access levels

​Use the key

​Security best practices

​Authentication errors

Create an API key

Key modes

Access levels

Use the key

Security best practices

Authentication errors