Skip to main content

Authentication

Authenticate every request to the Relasi.U Developer API with a bearer API key in the Authorization header:

Authorization: Bearer ru_live_<id>.<secret>

Create and manage keys in the dashboard under Settings → Developer / API → API Keys.

Keys & secrets​

  • The full key (ru_live_<id>.<secret>) is displayed only once upon creation. Store it in a secure secrets manager. If lost, you must rotate or revoke the key.
  • Each key carries an authoritative list of scopes defining its permissions.
  • You can optionally restrict a key to an IP allowlist (individual IPv4/IPv6 addresses or CIDR blocks such as 203.0.113.4, 10.0.0.0/24).

Available scopes​

ScopeDescription
messages:readRead messages and message details across conversations.
messages:writeSend text, attachments, and media replies into conversations.
conversations:readList conversations and inspect conversation details.
conversations:writeUpdate conversation status and attributes.
customers:readList contacts/customers and read detailed profiles.
customers:writeCreate, update, or merge contacts.
channels:readList connected omnichannel integration channels and inspect channel capabilities.
channels:writeModify channel settings.
sessions:manageManage session lifecycle: claim, assign, transfer, and resolve sessions.
campaigns:readRead marketing broadcast campaigns and metrics.
campaigns:writeCreate and trigger marketing broadcast campaigns.
analytics:readAccess aggregated analytics and workspace reports.
webhooks:readInspect webhook endpoints and delivery history.
webhooks:manageCreate, update, delete endpoints, and trigger redeliveries.
agents:readList and inspect workspace teammates/agents and assignability.

Rate limits​

Every API key has a token bucket rate limiter:

  • Baseline limit: 60 requests per minute per key.
  • Burst limit: Up to 100 requests per key.
  • When exceeded, the API returns HTTP 429 Too Many Requests.

Error responses​

Standard API error envelopes follow this format:

{
"error": "Insufficient scope",
"required_scope": "messages:write"
}
HTTP StatusMeaning
401 UnauthorizedMissing, malformed, revoked, or expired API key.
403 ForbiddenKey lacks the required scope, or client IP is not allowlisted.
404 Not FoundRequested conversation, message, or resource does not exist.
429 Too Many RequestsKey rate limit exceeded.
500 Internal Server ErrorUnexpected server failure.