Authentication
Create keys with the fewest scopes and send them from your server.
Every request carries an organization API key in the Authorization header. The key decides which organization you see and which operations you can call.
Create a key
Only owners and admins of the organization can create and revoke keys.
- Open Settings → API in Ricky.
- Enter a name that identifies the integration, for example
Store ERP. - Select only the scopes the integration needs.
- Choose the expiry: 90 days or 1 year.
- Select Create key and copy the key.
Ricky shows the full key once and stores only its SHA-256 digest. If you lose it, create another one.
A key has the form rky_live_ followed by 43 characters.
Send the key
curl https://getricky.ai/api/v1/members \
-H "Authorization: Bearer rky_live_…"Use the key only on your server. Never put it in a web page, a mobile app, a URL or a log. Keep it in a secret manager or an environment variable.
Lifetime
The key belongs to the organization and acts on behalf of the person who created it. It stops working in any of these cases:
- Someone revokes it in Settings → API. The effect is immediate.
- It reaches its expiry date.
- Its creator leaves the organization or loses the owner or admin role. Ricky checks this on every request.
A key that no longer works gets 401 unauthorized.
To rotate a key, create the new one, deploy it to your server and revoke the old one.
Scopes
Each operation requires one scope. A key without it gets 403 insufficient_scope.
| Scope | Allows |
|---|---|
contacts:read | Read contacts and contact fields. |
contacts:write | Create and update contacts. |
conversations:read | Read conversations, messages and channels. |
conversations:write | Assign, close and reopen conversations. |
messages:send | Start conversations, send messages and read sends. |
templates:read | Read WhatsApp templates. |
members:read | Read the members of the organization. |
tags:read | Read contact tags. |
webhooks:manage | Create, list and disable webhooks; read and retry their deliveries. |
The table below is generated from the API contract: it is the exact list of operations and the scope each one requires.
| Operation | Endpoint | Scope |
|---|---|---|
| List contacts | GET /contacts | contacts:read |
| Create a contact | POST /contacts | contacts:write |
| Get a contact | GET /contacts/{contact_id} | contacts:read |
| Update a contact | PATCH /contacts/{contact_id} | contacts:write |
| List contact fields | GET /contact-fields | contacts:read |
| List conversations | GET /conversations | conversations:read |
| Start a conversation | POST /conversations | messages:send |
| Get a conversation | GET /conversations/{conversation_id} | conversations:read |
| Assign a conversation | PATCH /conversations/{conversation_id}/assignment | conversations:write |
| Close a conversation | POST /conversations/{conversation_id}/close | conversations:write |
| Reopen a conversation | POST /conversations/{conversation_id}/reopen | conversations:write |
| List messages | GET /conversations/{conversation_id}/messages | conversations:read |
| Send a message | POST /conversations/{conversation_id}/messages | messages:send |
| Get a send | GET /sends/{send_id} | messages:send |
| List channels | GET /channels | conversations:read |
| List members | GET /members | members:read |
| List tags | GET /tags | tags:read |
| List templates | GET /templates | templates:read |
| List webhooks | GET /webhooks | webhooks:manage |
| Create a webhook | POST /webhooks | webhooks:manage |
| Disable a webhook | DELETE /webhooks/{webhook_id} | webhooks:manage |
| List deliveries | GET /webhooks/{webhook_id}/deliveries | webhooks:manage |
| Retry a delivery | POST /webhooks/{webhook_id}/deliveries/{delivery_id}/retry | webhooks:manage |
Authentication responses
| Situation | Response |
|---|---|
| The header is missing or malformed, or the key expired or was revoked | 401 unauthorized |
| The key lacks the operation's scope | 403 insufficient_scope |
| The key made more than 120 requests this minute | 429 rate_limited |