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.

Jun 26, 2026

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 Authorization header 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_id you 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

Was this helpful?

Related articles

Message us on WhatsApp