Tokens de API
- Qué son los tokens de API públicos y cuándo los necesitas
- Cómo crear, ver y gestionar tokens
- Mejores prácticas de seguridad para manejar tokens
Tokens de API Públicos permiten que aplicaciones externas, scripts y servicios se autentiquen con la API de AutoTalk. Gestionas los tokens desde la página Tokens de API en Integraciones en la barra lateral.
Cuándo necesitas tokens de API
Necesitas un token de API siempre que un sistema externo necesite comunicarse con AutoTalk programáticamente. Escenarios comunes incluyen:
- Conectar un CRM o helpdesk que envía o extrae datos de AutoTalk
- Construir una integración personalizada que envía mensajes o lee conversaciones a través de la API
- Configurar scripts de automatización que crean contactos, actualizan registros o disparan workflows
- Integrar plataformas no soportadas o sistemas internos a través de un puente personalizado, como un pipeline de notificaciones de Discord
Gestionar tokens
Ver tokens existentes
Navega a Integraciones > Tokens de API. La página lista todos tus tokens existentes. Puedes filtrar la lista, abrir un token para ver sus detalles y eliminar tokens; los tokens no se pueden editar tras crearlos.
Crear un nuevo token
- En la página Tokens de API, haz clic en el botón + (su tooltip muestra "Add new public_api_tokens").
- Revisa el alias generado o reemplázalo por una etiqueta propia.
- Elige los permisos. En Permisos, marca lo que la integración necesita en la cuadrícula de permisos, o parte de una plantilla (Solo lectura, Operador, Acceso total) y ajústala. Se requiere al menos uno: un token que no conceda nada no se puede guardar. Los permisos que no marcaste pueden aparecer marcados y bloqueados: uno más fuerte que sí marcaste los incluye. Consulta Permisos más abajo. Los permisos no se pueden cambiar después: un token que necesite otro conjunto hay que reemplazarlo.
- Elige una duración. Los tokens nuevos usan 90 días por defecto, con opciones de 7, 30, 90, 365 días o nunca expirar.
- Guarda el token.
- Copia inmediatamente el token generado o el comando MCP para Codex / Claude Code. El token completo se muestra solo una vez.
Ver o eliminar un token
- Haz clic en cualquier token de la lista para ver detalles, expiración y estadísticas de uso.
- Para revocar un token, elimínalo de la lista. Cualquier sistema externo que use ese token perderá acceso inmediatamente.
Usar tokens en solicitudes de API
Envía el token en el encabezado x-api-key en cada solicitud a la API pública de AutoTalk. Las claves siempre comienzan con sk-:
x-api-key: sk-YOUR_API_KEY
Ejemplo mínimo con curl:
curl -H "x-api-key: sk-YOUR_API_KEY" https://api.autotalk.io/v1/self
Consulta la Referencia de la API para el catálogo completo de endpoints.
Alternativa: x-jwt-token
La misma API también acepta JWT de corta duración a través del encabezado x-jwt-token (o del encabezado unificado x-auth-token, que detecta el prefijo sk- para enrutar automáticamente). Los JWT son emitidos internamente por la acción de workflow de agente actions/security/auth/jwt/generate — están pensados para agentes que llaman a la API pública en nombre de la propia empresa. Las integraciones externas deben seguir usando x-api-key. Consulta Autenticación para la especificación completa.
Mejores prácticas de seguridad
- Trata los tokens como contraseñas. Nunca los compartas en repositorios de código públicos, mensajes de chat o correos electrónicos.
- Usa nombres descriptivos. Etiqueta cada token con la integración o sistema al que pertenece, para poder identificarlo después.
- Revoca tokens no utilizados. Si una integración fue retirada o un token ya no es necesario, elimínalo inmediatamente.
- Rota tokens periódicamente. Reemplaza tokens en un cronograma regular para reducir el riesgo si uno es accidentalmente expuesto.
- Concede el conjunto más restringido que funcione. Se requiere al menos un permiso, y un token sigue concediendo todo lo que sus permisos implican: "Ejecutar workflows", por ejemplo, arrastra consigo todo lo que hacen los pasos del workflow. Usa un token separado por integración para que la revocación sea específica, y trata un token filtrado como el compromiso de todo lo que sus permisos cubren.
Permisos
Los permisos forman un árbol pequeño: elegir uno más fuerte incluye automáticamente los más débiles que cuelgan de él, y el selector los muestra ya marcados. Concede el conjunto más restringido que la integración realmente necesite.
| Permiso | Nombre en la API | Qué concede |
|---|---|---|
| Leer registros | data:read | Acceso de solo lectura a tus datos y sus esquemas |
| Crear, actualizar y eliminar registros | data:write | Escrituras en tus datos, incluidas las funciones de documento. Incluye data:read |
| Eliminaciones masivas y en cascada | data:admin | Eliminaciones destructivas y de alcance ilimitado. Incluye data:write |
| Enviar mensajes | messaging:send | Mensajería en tus canales, además de eliminar chats y mensajes |
| Leer archivos | storage:read | Leer y listar archivos almacenados |
| Subir archivos | storage:write | Escribir en el almacenamiento. Incluye storage:read |
| Eliminar archivos | storage:admin | Eliminar archivos. Incluye storage:write y storage:share |
| Enlaces para compartir | storage:share | Crear URLs de descarga utilizables fuera de AutoTalk. Solo la incluye storage:admin, nunca lectura ni escritura |
| Ejecutar IA facturada | ai:run | Generación con LLM y transcripción que cuestan dinero |
| Ejecutar workflows guardados | workflows:run | Ejecuta un workflow que esta cuenta ya escribió, incluidos los registros, mensajes, archivos e IA que usan sus pasos. No crea, edita ni activa uno |
| Automatización y código | automation:admin | Ejecución de código arbitrario. También crear y activar workflows, HTTP saliente, emitir tokens y leer secretos almacenados |
| Administración de la cuenta | org:admin | Todo lo de las diez áreas siguientes a la vez |
| Equipo | org.team:admin | Invitaciones y empleados |
| Facturación | org.billing:admin | Presupuesto, créditos y suscripciones |
| Canales | org.channels:admin | Canales e integraciones, incluidas las acciones de moderación en la plataforma conectada |
| Tipos personalizados | org.types:admin | Crear y modificar tipos personalizados |
| Webhooks | org.webhooks:admin | Configuración de webhooks — y por tanto salida saliente configurada |
| Agentes y perfiles | org.agents:admin | Agentes, perfiles de transcripción y perfiles de voz |
| Claves de API | org.keys:admin | Reemitir el secreto de una clave de API |
| Exportación de datos | org.export:admin | Transferencia y exportación de datos |
| Onboarding | org.onboarding:admin | Flujos de incorporación |
| Depuración del agente | org.debug:admin | Herramientas de depuración del agente de IA |
| Acceso total | account:admin | Todos los permisos anteriores |
Dos consecuencias del árbol que conviene decir explícitamente:
- "Ejecutar workflows guardados" conlleva autoridad real. La ejecución de un
workflow ejerce todo lo que hacen sus pasos, así que este permiso incluye acceso
a datos, mensajería, archivos e IA. Lo que no incluye es la autoría: crear,
editar o activar un workflow es
automation:admin. automation:admines una valla. Nada lo implica salvo el acceso total. Un workflow cuyos pasos ejecutan código, llaman a una URL externa o emiten un token se rechaza por completo si la clave no lo tiene.
Una llamada que los permisos del token no cubren se rechaza con HTTP 403 y
el código de error scope_denied. La respuesta nombra el permiso que faltaba.
Si sospechas que un token ha sido comprometido, revócalo inmediatamente eliminándolo de la lista de Tokens de API, luego crea uno nuevo y actualiza la integración afectada.
Próximos pasos
- Referencia de la API — Navega por todos los endpoints y esquemas disponibles de la API (documentación interactiva)
- Webhooks — Configura notificaciones de eventos salientes
- Agregar una integración — Guía general de configuración de canal