Skip to main content

Authentication

The Mojeeb Public API uses API keys, not JWTs. Each key is a long-lived server-to-server credential issued from the dashboard, scoped to your organization, and may be restricted to specific agents and specific actions. Send the key as a Bearer token over HTTPS.

How do I send my API key?​

Pass the key in the standard Authorization header:

Authorization: Bearer mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

HTTPS only. Plain HTTP requests are rejected by the load balancer before they reach the API.

What does the key format look like?​

mk_live_<22 chars>_<10 char checksum>

Example: mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5
  • mk_ — Mojeeb prefix; grep-able in logs
  • live_ — environment marker (test_ is reserved for a future sandbox)
  • 22-character body with 130 bits of entropy
  • 10-character checksum so the API can reject malformed keys before any database lookup

The checksum protects you against typos: a one-character mistake fails locally, fast.

Where do I get a key?​

  1. Sign in to the Mojeeb dashboard (Professional plan or higher)
  2. Open the API Keys page from the sidebar
  3. Click Create key, give it a name, and confirm
  4. Copy the secret immediately — it's shown once and never again

If you lose a key, revoke it from the dashboard and create a new one. There is no way to recover the original secret.

What are scopes?​

Scopes restrict what a key can do, in resource:action format. The default and most common scope is:

ScopeAllows
whatsapp:sendSend WhatsApp text messages and templates
whatsapp:read(Reserved) Read WhatsApp message status and history
messenger:send(Reserved) Send Facebook Messenger messages
instagram:send(Reserved) Send Instagram DMs
*Wildcard — all current and future scopes (use sparingly)

A request without the required scope returns 403 insufficient_scope with a required_scope field telling you exactly what was missing.

Can I restrict a key to specific agents?​

Yes. When creating a key, optionally pick one or more agents. The key can only act on those agents — requests to any other agent_id return 403 agent_not_authorized.

Leave the agent list empty for an unrestricted key that works across every agent in the organization. Use restricted keys when integrating a single product or workflow that should only touch a specific agent (recommended for least-privilege).

What happens when authentication fails?​

Every authentication failure returns HTTP 401 with the standard error envelope. A single code (invalid_api_key) covers every sub-case so your client only needs one branch — the message field disambiguates for humans:

Sub-casemessage
Missing Authorization headerMissing Authorization header. Send 'Authorization: Bearer mk_live_...'.
Wrong scheme (e.g. Basic)Authorization header must use the Bearer scheme.
Malformed, unknown, revoked, or expired keyThe API key is invalid, malformed, or revoked.

Example response:

{
  "error": {
    "type":           "authentication_error",
    "code":           "invalid_api_key",
    "message":        "The API key is invalid, malformed, or revoked.",
    "correlation_id": "req_01KQER73VQBSZK5RPVZCPW221V"
  }
}

Common questions​

Should I rotate keys regularly?​

Yes. Treat API keys like database credentials — rotate every 90 days, rotate immediately if a key may have leaked, and use separate keys for separate environments and integrations so revocation has narrow blast radius.

Can I use the same key from multiple servers?​

Yes. The key isn't IP-bound. The rate limit (default 60 req/min) is per key, so multiple servers sharing one key share the budget. For independent rate budgets, issue separate keys.

Is there a sandbox/test environment?​

Not yet. The test_ environment marker is reserved in the key format but not currently issued. Develop against your live agents with a restricted key in the meantime, and use idempotency keys so retries during development don't multiply sends.

What's the difference between API key auth and the dashboard's JWT?​

The dashboard authenticates users via JWT issued at login. The public API authenticates servers via long-lived API keys. Internally both produce the same authorization context — the same per-agent permission checks apply — but API keys can't be used in the browser dashboard, and JWTs can't be used against /v1/ endpoints.