User vs bot tokens and using tokens in HTTP requests
Understand the difference between a user token and a service (bot) token, and learn how to send your API key in HTTP requests to the Omnifox API.
Watch this step in the video · Create an API key
When you create an API key you can mark it as a Service token (bot). That choice changes how messages and events generated with the key behave. This article covers the difference and how to send the token in your HTTP requests.
User token vs service (bot) token
User token (Service token checkbox unchecked): actions are attributed to you as a human agent. Use it to automate your own work.
Service token (bot) (checkbox checked): designed for integrations (n8n, Zapier, scripts). With a bot token:
- Sent messages are not auto-assigned to the user who owns the key.
- They don't affect the user's online status.
- They don't trigger push notifications to the user's device.
Rule of thumb: if a machine uses the key, mark it as a bot. If you use it to speed up your own manual work, leave it as a user token.
Using the token in HTTP requests
The Omnifox REST API lives under /api/v1/. Authenticate every request with the Authorization: Bearer header:
Authorization: Bearer 123_aBc...yourFullToken
Accept: application/json
cURL example to list contacts:
curl https://omnifox.io/api/v1/contacts \
-H "Authorization: Bearer 123_aBc...yourFullToken" \
-H "Accept: application/json"
Workspace
The key is already bound to one workspace (the one you chose when creating it). That's the source of truth: if you send a workspace_id in the request, it must match the key's, or the API rejects it. You don't need to pass it when the key already has one set.
Scopes
Each endpoint requires the matching scope. If the key lacks, say, write:messages, sends will fail with a permission error. Review scopes and permissions.
Verify it worked
A 200 OK response with data confirms the token and scopes are correct.
If it doesn't work
- 401 Unauthorized: token missing, mis-copied, or expired. Check the
Authorizationheader and that the key hasn't expired. - 403 / scope error: the key lacks the endpoint's permission. Edit the key and add the scope.
- Workspace error: the
workspace_idyou sent doesn't match the key's. Drop the parameter or use the key from the right workspace. - My messages get assigned to me unintentionally: you used a user token; recreate the key as a bot.
Tip
Store the token in an environment variable (OMNIFOX_TOKEN) and never commit it to a repository.
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.