Claves de API y permisos
Las claves de API autentican a tus servidores cuando llaman a la API REST de CustomerHero. Cada clave está vinculada a una sola organización y a un conjunto específico de permisos.
Crear una clave
Ve a Ajustes → Claves de API → Nueva clave. Pon un nombre descriptivo (p. ej. "Backend de producción", "Worker de staging"), elige los permisos que necesita y copia el secreto. El secreto se muestra solo una vez: guárdalo en tu gestor de secretos inmediatamente.
Las claves tienen el formato sk_live_…. Envíalas como Bearer token en cada solicitud:
curl https://us.api.customerhero.app/api/orgs/ORG_ID/chatbots \
-H "Authorization: Bearer sk_live_your_api_key_here"Permisos (scopes)
Los permisos empiezan por el verbo y se agrupan por recurso. Concede el conjunto más estrecho posible para que tu integración haga su trabajo: nunca otorgues admin:* o * a una clave que solo necesita leer clientes.
| Permiso | Concede |
|---|---|
| chat:write | Enviar mensajes a un chatbot desde un servidor (endpoint público de chat). |
| inbox:read | Listar y leer conversaciones, mensajes y asignaciones. |
| inbox:write | Responder, cambiar estado, asignar, etiquetar y añadir notas internas. |
| customers:read | Listar y leer registros de clientes y empresas. |
| customers:write | Crear, actualizar, fusionar y eliminar clientes y empresas. |
| chatbots:read | Listar chatbots y leer su configuración. |
| chatbots:write | Crear, actualizar y eliminar chatbots, fuentes de datos y acciones. |
| billing:read | Leer plan, uso, saldo de créditos y facturas. |
| admin:* | Operaciones de admin de la org: miembros, roles, SSO, webhooks. Úsalo con cuidado. |
| * | Todo. Evítalo en producción. |
Un sufijo :* concede todas las acciones del grupo: p. ej. chatbots:* incluye chatbots:read y chatbots:write. Una solicitud con permisos insuficientes recibe HTTP 403 con {"error":"Missing scope: ..."}.
Rotación
Rota las claves al menos cada 90 días, e inmediatamente si una clave puede haberse filtrado. El patrón seguro es en dos pasos:
- Crea una clave nueva con los mismos permisos, despliégala en tus servidores y verifica que el tráfico llega por la nueva.
- Revoca la clave anterior. La revocación es inmediata: las solicitudes en curso con la clave antigua reciben HTTP
401en su siguiente llamada.
Cada clave muestra un timestamp de último uso en la página de ajustes para que confirmes que la nueva está recibiendo tráfico antes de revocar la antigua.
Buenas prácticas
- Solo en el servidor. Nunca incrustes una clave en el navegador, una app móvil ni un repositorio público. El widget no necesita una clave de API: usa endpoints públicos por chatbot.
- Una clave por servicio. Claves separadas para cada backend, y separadas para staging y producción. Así revocar una no derriba cargas no relacionadas.
- Restringe por IP cuando puedas. En los planes Business y Enterprise puedes restringir claves a una lista CIDR desde sus ajustes.
- Registro de auditoría. Cada creación, cambio de permiso y revocación queda registrada en el log de auditoría de la org. Revísalo tras onboardings/offboardings.
Próximos pasos
Empieza a llamar a la API en la referencia de la API, o suscríbete a eventos de webhook.