API Key Management

Mersal uses two separate credential types for API access. They live in different places in the dashboard, they authenticate differently, and they are not interchangeable — mixing them up is one of the most common integration mistakes. See Authentication for the full technical contract; this page focuses on finding, rotating, and handling both keys safely.

Your channel API key

This is the key that authenticates POST /api/sms/send, POST /api/whatsapp/send, POST /api/email/send, and the corresponding GET /api/get/{channel}/{id?} lookup endpoints. It's sent via the Api-key header (or a query/body fallback), not as a Bearer token.

Where to find it: your account's API key page in the dashboard, under account settings.

What it can do: send messages on any channel your account has a connected gateway for, and consume your account's sending allowance. Anyone with this key can send on your behalf and spend your credits — treat it exactly like a password.

Your AI Pool key

This is a distinct credential used only for the AI Gateway (POST /api/ai/v1/chat/completions, GET /api/ai/v1/models). It's sent as a standard Bearer token:

Authorization: Bearer <ai-pool-key>

Where to find it: the AI Pool / AI Gateway section of the dashboard — a separate screen from your channel API key.

Best practices

• Never expose either key in client-side or browser code. Both keys should only ever be used from your own backend. A key embedded in a mobile app, a frontend bundle, or any code a user's browser can read is effectively public.
• Rotate a key if you suspect it leaked — committed to a public repository, pasted into a shared document, logged somewhere it shouldn't be, or shared with someone who no longer needs it. Regenerating a key immediately invalidates the old one, so update every integration using it before you rotate, or plan for a brief cutover.
• Treat both keys like passwords. Don't send them over unencrypted channels, don't paste them into chat tools or tickets you can avoid, and don't reuse them across unrelated systems.
• Scope your usage mentally, even if the platform doesn't split keys further. If different systems integrate with Mersal (a website, a mobile backend, an internal tool), consider which of them actually needs sending capability versus which only needs to read status — and limit exposure of the key to only the systems that need it.

Next steps

• Authentication — the full request/response contract for both key types.
• Platform Security Overview — the broader picture of account and data protection.