Authentication
Create a scoped org token and send it as a bearer token.
The API authenticates with org-scoped bearer tokens. Every request operates inside the token's organization only — a token can never reach another org's data.
An org token sees every agent's leads in its org, not just the leads of whoever created it. In the dashboard, agents see their own inbox unless they opt into sharing; an API token deliberately crosses that boundary, because a CRM sync is useless with a partial pipeline. Only org admins can create one.
Create a token
In the dashboard, go to Settings → Integrations → Webhook (admin only). Pick a scope, optionally set an expiry, and create the token — it's shown once, so copy it immediately and store it as a secret. Reply First keeps only a hash; it can't show you the value again.
Tokens look like:
rf_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxScopes
Scopes are ranked, not orthogonal: a higher scope satisfies every requirement below it. A send token can do everything; a read token can only read.
| Scope | Grants |
|---|---|
read | Every GET: list and read leads, conversations, messages, handoffs, and stats. |
write | Everything in read, plus creating and updating leads and accepting/resolving handoffs. |
send | Everything in write, plus sending messages to contacts. |
Pick the lowest scope that does the job. A reporting integration that only reads the pipeline should be read — then a leaked token can't change or send anything.
A token whose scope is too low returns 403 with code: "FORBIDDEN_SCOPE":
{
"error": "This endpoint requires the \"send\" scope; your token has \"write\".",
"code": "FORBIDDEN_SCOPE",
"details": { "required_scope": "send", "token_scope": "write" }
}Tokens created before scopes existed behave as write — their original capability. They can read and write leads, but not send messages.
Send it
Pass the token in the Authorization header on every request:
curl https://replyfirst.ae/api/v1/me \
-H "Authorization: Bearer $RF_ORG_TOKEN"GET /api/v1/me is the cheapest way to check a token: it's side-effect free and tells you the org, the scope, and the expiry.
A missing, malformed, revoked, or expired token returns 401.
Expiry
A token can be created with an expiry of 1–365 days, or with none at all. An expired token stops working immediately and returns 401 — there is no grace period, so rotate before the expiry date.
Rotate and revoke
Create a new token before retiring an old one, update your integration, then revoke the old token in settings. Revocation takes effect immediately — the check is a live lookup on every request, not a cached claim.
Treat rf_org_ tokens like passwords. Keep them in a secret manager, never in client-side code or a committed file.