Skip to content

API and SDK

Authentication and API keys

How to create, use and protect the keys that authenticate the /v1 API.

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.

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 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.

Send the key in the Authorization header with the Bearer scheme, on every request:

Janela do terminal
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.

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.

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.

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:

Janela do terminal
# create a connection key
curl -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"]}'
# rotate
curl -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"}'
# revoke
curl -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.

  • 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.

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.