What a Workspace API Key is for
A Workspace API Key lets an integration call the Octopods API for actions scoped to one Intercom or HubSpot workspace — for example, sending messages through any channel connected to that workspace. Each workspace has its own key, generated on demand.
Two other key types exist in Octopods — Channel API Keys (scoped to a single channel such as one SMS line or one Telegram bot) and WhatsApp Business API Keys (one per WhatsApp Business Account). Those are managed from the relevant channel’s detail page, not from the Settings page this article covers. See API Key Authentication for the full picture.
Open the API Keys page
Sign in to Octopods.
Click your user menu in the top-right corner and choose Settings.
In the left sidebar, click API Keys (labeled “Workspace integrations”).
You land on a section titled “API Keys” with the subtitle “API keys for your Intercom workspaces.” Inside, the Workspace API Keys card lists every workspace connected to your account.
What the table shows
The Workspace API Keys table has three columns:
Column | What it shows |
Workspace | The name of the Intercom or HubSpot workspace. |
API Key | The generated key value in a read-only field, or “No API key generated” if none exists yet. |
Actions | A Create API Key button when no key exists, or a copy icon button when one does. |
Each row represents one workspace. Workspaces that have never had a key show the placeholder text “No API key generated” in the middle column.
Create a Workspace API Key
On the API Keys page, find the row for the workspace you want a key for.
Click Create API Key in the Actions column.
The page refreshes and the new key appears in the API Key column, already populated in the read-only field.
The key takes effect immediately — you can start using it in API requests right away.
Important: Each workspace has exactly one active Workspace API Key at a time. Once a key exists for a workspace, the Create API Key button is replaced by the copy icon, and the existing key continues to appear every time you return to this page.
Copy a key
The key is displayed in a read-only text field next to a copy button.
Find the workspace row with the key you want.
Click the copy icon next to the key value.
A green checkmark briefly appears in place of the icon to confirm the key was copied to your clipboard.
Paste the key into your integration, secrets manager, or wherever it will be used.
Because the key is visible every time you visit this page, you can re-copy it as often as you need.
Use the key in an API request
Pass the Workspace API Key in the X-Octopods-Auth request header on every API call:
X-Octopods-Auth: YOUR_WORKSPACE_API_KEY
There is no Bearer prefix and no other header scheme. A missing or invalid key returns a 401 Unauthorized response. For endpoint-specific details, see API Key Authentication.
Rotating or revoking a key
Workspace API Keys cannot currently be rotated or deleted from the Settings page. If you need to replace or revoke a key — for example, because it was accidentally committed to a public repository, shared in a screenshot, or exposed to someone who should no longer have access — contact Octopods support to have the key rotated.
Until the key is rotated, treat it as compromised: audit recent activity from integrations that used it, and assume anyone who saw the key can still use it.
Who can manage keys
Every member of the account can open the API Keys section in Settings, generate a Workspace API Key for any connected workspace, and copy an existing one. There is no separate admin-only restriction on this page.
Because the key unlocks every channel in a workspace, this means account access and key access are effectively the same thing. Limit who you invite to the account, and rotate any key that was handled by someone who no longer needs it (see the security best practices below).
For role details in other parts of the product, see Managing Team Member Roles.
Security best practices
A Workspace API Key unlocks every channel connected to that workspace. Handle it the same way you handle a password.
Store keys in a secrets manager. Never commit a key to source control, check it into a config file, or paste it into a chat channel. Use whatever secrets solution your team already relies on — cloud provider secret stores, HashiCorp Vault, 1Password, and similar.
Keep keys server-side. Workspace API Keys belong in server-to-server calls, never in browser code, mobile apps, or anywhere a user could inspect the request.
Use the narrowest-scoped key. If your integration only needs to send through one channel, use that channel’s Channel API Key instead of a Workspace API Key. Rotating a narrower key only affects one integration.
Rotate on personnel changes. When someone who had access to a key leaves your team, request a rotation so they can no longer act on the workspace’s behalf.
Rotate immediately if a key leaks. An accidental commit, screenshot, email, or log entry containing a key means the key is compromised. Request a rotation and replace it everywhere you use it.
Limit who can copy keys. Only admins who need to set up integrations should handle the keys. Share generated keys through your secrets manager, not by email or chat.
What’s next