API and SDK
Authentication and API keys
How to create, use and protect the keys that authenticate the /v1 API.
Create the key in the panel
Section titled “Create the key in the panel”In API keys → Create key, fill in:
| Field | What it is |
|---|---|
| Name | Up to 32 characters, to recognize the key later (production, crm) |
| Permissions | send (send messages), read (read connections, conversations and logs), templates (create and edit templates) and admin (everything). Tick only what the integration uses |
| Connections | All connections or only the selected ones. A key bound to connections cannot see the others |
| Expiration | 30, 90, 180 or 365 days, or Never expires |
| Limit per minute | From 1 to 6,000 requests per minute (default: 600). See Limits |
Owners, admins and devs create keys. Only owners and admins can grant the admin permission. Once created, a key can be edited (name, permissions, connections, limit), disabled, re-enabled or revoked.
Key types
Section titled “Key types”Organization key (mj_) |
Connection key (mjc_) |
|
|---|---|---|
| Where to create | API keys, at the organization level | The connection’s API keys tab |
| Reach | Any connection in the org; connection_id required on message routes |
Only its own connection; connection_id is optional (if sent and different, 403 connection_not_allowed) |
| Destinations | Global and any connection’s | Only its own connection’s, never global |
| Connections | List, update and disconnect | Read and update its own; cannot disconnect |
| Connection links | Yes | 403 organization_key_required |
Manage connection keys via /v1 |
Yes, with the admin permission |
No |
| Events, deliveries, logs and costs | The whole org | Only the connection’s (plus WABA events) |
GET /v1/me |
api_key.kind = "org", null connection_id and connection |
api_key.kind = "connection", with connection_id and connection { id, channel, label } |
Permissions (send, read, templates, commerce, admin) apply to both types. Use one connection key per integration: it only sees its own number and does not need connection_id. Older organization keys bound to several connections keep working, but the panel no longer offers that option.
Templates, flows and catalogs belong to the WABA: a connection key that changes them also affects the sibling connections on the same WABA.
The key is shown once
Section titled “The key is shown once”The full value, starting with mj_ (organization) or mjc_ (connection), only appears in the creation dialog. Messajo stores only a hash: neither the panel nor support can show it again. Lost it? Create another one and revoke the old one.
To recognize the key later, the panel shows the visible prefix, its first 10 characters (for example, mj_A1b2c3d). The same prefix comes back in the api_key.start field of GET /v1/me.
Authorization: Bearer
Section titled “Authorization: Bearer”Send the key in the Authorization header with the Bearer scheme, on every request:
curl https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY"A panel session cookie never authenticates the /v1 API: a request with only a cookie gets missing_api_key. Keys in the query string are not accepted either.
Authentication errors
Section titled “Authentication errors”Every error uses the API’s single error body, with a stable code:
{ "error": { "code": "missing_api_key", "message": "Missing API key: send Authorization: Bearer <key>", "meta_code": null, "retryable": false, "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b", "docs_url": "https://docs.messajo.com/errors#missing_api_key" }}| Status | code |
When |
|---|---|---|
| 401 | missing_api_key |
The Authorization: Bearer header is missing |
| 401 | invalid_api_key |
The key does not exist or was revoked |
| 401 | api_key_expired |
The key has expired |
| 401 | api_key_disabled |
The key was disabled in the panel |
| 403 | insufficient_permissions |
The key lacks the permission the route requires |
| 403 | connection_not_allowed |
The key is bound to other connections |
| 403 | organization_key_required |
The route is organization-key only and the key is a connection key |
None of these errors goes away by retrying (retryable: false): fix the key or its permissions.
Test in /reference
Section titled “Test in /reference”The interactive reference lives at https://api.messajo.com/reference. Paste the key under Authentication and use Test request to call the real routes, such as GET /v1/me.
The call goes from your browser to the server itself, on the same origin, without any third-party proxy. The reference in these docs is read-only and sends no requests.
Rotate a key
Section titled “Rotate a key”In the panel, Rotate creates a new key with the same name, type, permissions, connection and limit, and shows the new value once. The old key keeps working for a grace period: 24 hours (default) or now, which ends it immediately. The grace period never exceeds the original expiration. A disabled or expired key cannot be rotated.
Through /v1, an organization key with admin creates, rotates and revokes connection keys only (grace: 24h or now). Organization keys are rotated in the panel; /v1 returns 404 not_found for them:
# create a connection keycurl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "crm", "permissions": ["send", "read"]}'
# rotatecurl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"grace": "24h"}'
# revokecurl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \ -H "Authorization: Bearer $MESSAJO_API_KEY"The rotation response carries the new secret and previous_key_expires_at, when the old key’s grace period ends. Full fields are in the reference.
Good practices
Section titled “Good practices”- Environment variable or secrets manager, never in code or in the repository.
- Never in the browser or a mobile app. Anyone can extract a key from a front end. Call Messajo from your back end.
- One key per integration, with the fewest permissions and, when possible, bound to the connections it uses. If one leaks, you revoke only that one.
- Set an expiration for test and third-party keys.
- Rotate without downtime: create the new key, swap it in the integration, check the old key’s last used in the panel and only then revoke it. The last used time updates at most every ~5 s per replica and the request counter is not exact per call (key verification is cached for 5 s).
- Leaked? Revoke it right away. The next call with it already gets
invalid_api_key.
X-Request-Id for support
Section titled “X-Request-Id for support”Every response, success or error, carries the X-Request-Id header (req_…). The same value appears in request_id in error bodies and in GET /v1/me.
Log this value in your integration. When asking for help, send the X-Request-Id: with it, support finds the exact call without you sending the key.