Get started

One kind of key, for your account. The key acts as itself.

• A key belongs to your account. It acts on one client per call: the one it is pinned to, otherwise the one named by the Nodium-Tenant header, otherwise your own company (My company). Anything outside your account answers 404, never 403.
• A key acts as itself, not as the person who created it. Messages it sends carry the key's label. Removing that person does not revoke the key.
• A key opens the whole published API of your account, and nothing else. Keys are created in the console or with POST /keys; the secret is shown once, and Nodium keeps only its hash. A revoked key is refused on its very next call.
• A key never expires unless you say so: expiresInDays (1 to 3650) in POST /keys fixes an end date, returned as expiresAt. Past it, the key answers 401 with api_key_expired and shows as inactive. Rotate by creating a new key, deploying it, then revoking the old one.

Choosing the client

• Add Nodium-Tenant: <id or externalId> to any call to act on that client. Without it, the call acts on the key's client, or on My company.
• Pin a key to one client with clientId in POST /keys: it can never leave that client, and a header naming another one answers 404.
• Only a key that is not pinned sees every client: it alone manages /tenants and /keys, and the webhook subscriptions of My company, which carry every client's events (a key pinned to My company gets 404 there).
• See Your clients.

Limits

600 calls per minute per client for a key that acts on every client of your account (the client is named by Nodium-Tenant), with a ceiling of 6,000 per key; 600 per minute for a key pinned to one client. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Above the limit you get 429 with rate_limited and a Retry-After header in seconds. Free-form messages (POST /messages, every type except template) have their own limit, 600 per minute per key and per client; templates do not. A key that acts on several clients has its own 600 for each of them. To send in volume without waiting on each call, use queue: true (see Sending).

Quota

Messages sent and received (templates included) are counted together across your whole account, from the plan's monthly allowance. Receipts and test channels do not count. The allowance resets on the 1st of the month at midnight UTC. On the free plan (Build) sends are blocked once it is used up: they answer 402 with quota_exceeded, without any earlier warning; messages you receive still come in. On a paid plan each extra block of 1,000 messages is billed, up to an overage cap you set in your billing space; at the cap sends stop with the same 402. Phone numbers and stored media have their own allowance: a number beyond it is billed on a paid plan and refused (402 with plan_limit) on Build, and media beyond the storage allowance is refused on Build (402 with storage_quota). GET /billing/summary shows the month so far. Meta's own fees are never included: your clients pay them to Meta.

Your calls, logged

Every call made with a key over the last 30 days is listed in the console and by GET /api-requests: address, status, error code, duration, request id. No body, header or query string is kept.