The authentication header
Every request to the Octopods API must include the X-Octopods-Auth header with your API key as its value. No Bearer prefix, no other header scheme.
X-Octopods-Auth: YOUR_API_KEY
Requests without a valid key receive a 401 Unauthorized response. Requests whose key has been rotated or revoked receive a 400 Bad Request with error code DEPRECATED_API_KEY — when that happens, fetch the new key from Octopods and update your integration.
The three key types
Octopods issues three different API keys depending on what you want to do. Each key is scoped to a specific resource — always pick the key that matches the endpoint you’re calling.
Workspace API Key
Scoped to one Intercom or HubSpot workspace. Used by integrations that act at the workspace level — for example, sending SMS, Viber, or Telegram messages from any channel inside that workspace.
Where to find it: Settings → API Keys → Workspace API Keys. Every workspace in your account is listed here.
Open Octopods and click Settings.
Select API Keys from the left sidebar.
Find the row for your workspace under Workspace API Keys.
If no key exists yet, click Create API Key. Otherwise, click the copy icon next to the existing key.
Channel API Key
Scoped to a single channel (one SMS line, one Telegram bot, one Viber Business Messages sender, and so on). Used when you want an integration to send only through that specific channel.
Where to find it: open the channel’s detail page from Channels. The key appears in a card on the page, labeled according to the channel type — for example, Twilio API Key on an SMS channel, VBM API Key on a Viber channel, or Telegram API Key on a Telegram channel.
In Octopods, go to Channels.
Click the channel you want to automate.
Copy the key shown in the API key card on the channel’s detail page.
WhatsApp Business API Key
A dedicated key for the WhatsApp API. One key per WhatsApp Business Account (WABA), shared across every WhatsApp number attached to that account. This key also governs the WhatsApp interactive API and the WhatsApp templates API.
Where to find it: open any WhatsApp channel and look at the Message Templates API card on the channel detail page.
Go to Channels and open a WhatsApp channel.
Locate the Message Templates API card.
Copy the value shown under WhatsApp Business API Key.
Which key for which endpoint
Endpoint family | Key to use |
| WhatsApp Business API Key |
| WhatsApp Business API Key |
| WhatsApp Business API Key |
| WhatsApp Business API Key |
| Channel API Key (SMS channel) |
| Channel API Key (Viber channel) |
| Channel API Key (Viber channel) |
| Channel API Key (Telegram channel) |
Example request
A complete, authenticated request to send an SMS message looks like this:
POST https://app.octopods.io/api/v1/sms/messages
X-Octopods-Auth: YOUR_CHANNEL_API_KEY
Content-Type: application/json{
"destination_phone": "+15551234567",
"body": "Hello from Octopods."
}
Key security best practices
Treat keys like passwords. Anyone with a key can send messages from the corresponding channel or workspace. Store keys in a secrets manager, not in source code or version-controlled config files.
Do not expose keys in front-end code. Keys belong in server-side requests only. A key embedded in a browser, mobile app, or public repo is compromised.
Use the narrowest-scoped key that works. Prefer a Channel API Key over a Workspace API Key when the integration only needs to use one channel — that way, rotating the key affects only the one integration.
Rotate on personnel changes. If someone who had access to a key leaves your team, generate a new key and retire the old one.
Rotate if a key leaks. Any accidental commit, screenshot, or log entry containing a key should trigger immediate rotation.
What’s next