Tokens de usuario vs bot y usar tokens en requests HTTP
Entiende la diferencia entre un token de usuario y uno de servicio (bot), y aprende a enviar tu clave API en peticiones HTTP a la API de Omnifox.
Mira este paso en el video · Crear una clave API
Al crear una clave API puedes marcarla como Token de servicio (bot). Esa decisión cambia cómo se comportan los mensajes y eventos generados con esa clave. En este artículo vemos la diferencia y cómo usar el token en tus peticiones HTTP.
Token de usuario vs token de servicio (bot)
Token de usuario (casilla Token de servicio desmarcada): las acciones se atribuyen a ti como agente humano. Sirve para automatizar tu propio trabajo.
Token de servicio (bot) (casilla marcada): pensado para integraciones (n8n, Zapier, scripts). Con un token bot:
- Los mensajes enviados no se auto-asignan al usuario propietario de la clave.
- No afectan el estado en línea (online) del usuario.
- No disparan notificaciones push al dispositivo del usuario.
Regla práctica: si la clave la usa una máquina, márcala como bot. Si la usas tú para acelerar tu trabajo manual, déjala como token de usuario.
Usar el token en requests HTTP
La API REST de Omnifox vive bajo /api/v1/. Autentica cada petición con el encabezado Authorization: Bearer:
Authorization: Bearer 123_aBc...tuTokenCompleto
Accept: application/json
Ejemplo con cURL para listar contactos:
curl https://omnifox.io/api/v1/contacts \
-H "Authorization: Bearer 123_aBc...tuTokenCompleto" \
-H "Accept: application/json"
Workspace
La clave ya está atada a un workspace (el que elegiste al crearla). Esa es la fuente de verdad: si envías workspace_id en la petición, debe coincidir con el de la clave o la API lo rechaza. No hace falta pasarlo si la clave ya lo tiene fijado.
Scopes
Cada endpoint exige el scope correspondiente. Si la clave no tiene, por ejemplo, write:messages, los envíos fallarán con un error de permisos. Revisa scopes y permisos.
Verificación
Una respuesta 200 OK con datos confirma que el token y los scopes son correctos.
Si no funciona
- 401 Unauthorized: token ausente, mal copiado o caducado. Verifica el encabezado
Authorizationy que la clave no haya vencido. - 403 / error de scope: a la clave le falta el permiso del endpoint. Edita la clave y agrega el scope.
- Error de workspace: el
workspace_idenviado no coincide con el de la clave. Quita el parámetro o usa la clave del workspace correcto. - Mis mensajes aparecen asignados a mí sin querer: usaste un token de usuario; recrea la clave como bot.
Tip
Guarda el token en una variable de entorno (OMNIFOX_TOKEN) y nunca lo subas a un repositorio.
Artículos relacionados
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.