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
| Scope | Description |
|---|---|
messages:read | Read messages and message details across conversations. |
messages:write | Send text, attachments, and media replies into conversations. |
conversations:read | List conversations and inspect conversation details. |
conversations:write | Update conversation status and attributes. |
customers:read | List contacts/customers and read detailed profiles. |
customers:write | Create, update, or merge contacts. |
channels:read | List connected omnichannel integration channels and inspect channel capabilities. |
channels:write | Modify channel settings. |
sessions:manage | Manage session lifecycle: claim, assign, transfer, and resolve sessions. |
campaigns:read | Read marketing broadcast campaigns and metrics. |
campaigns:write | Create and trigger marketing broadcast campaigns. |
analytics:read | Access aggregated analytics and workspace reports. |
webhooks:read | Inspect webhook endpoints and delivery history. |
webhooks:manage | Create, update, delete endpoints, and trigger redeliveries. |
agents:read | List 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 Status | Meaning |
|---|---|
401 Unauthorized | Missing, malformed, revoked, or expired API key. |
403 Forbidden | Key lacks the required scope, or client IP is not allowlisted. |
404 Not Found | Requested conversation, message, or resource does not exist. |
429 Too Many Requests | Key rate limit exceeded. |
500 Internal Server Error | Unexpected server failure. |