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.
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.

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 until it 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

Conversations

Knowledge

Create an API key

Key modes

Use the key

Security best practices

Authentication errors

​Create an API key

​Key modes

​Use the key

​Security best practices

​Authentication errors

Create an API key

Key modes

Use the key

Security best practices

Authentication errors