developers
EN Crear cuenta

Empezar

Autenticación

Cada solicitud lleva una API key del workspace. La key decide a qué workspace hablas y qué puedes hacer en él.

Manda la key como token Bearer en cada solicitud:

header
Authorization: Bearer sk_live_...

Las keys tienen el formato sk_live_ seguido de 43 caracteres. heysteff guarda solo un hash: si pierdes el secreto, no se puede recuperar; crea otra key o rota la que tienes.

Crear una key#

  1. Entra al panel en app.heysteff.com.
  2. Ve a Configuración → Desarrolladores → API Keys y toca Nueva API key.
  3. Elige los scopes mínimos que necesita tu integración y, si quieres, las IPs desde las que se puede usar.
  4. Copia el secreto y guárdalo en tu gestor de secretos o en una variable de entorno.

Scopes#

Cada operación exige un scope. Una key sin el scope recibe 403 forbidden. Dale a cada integración solo lo que usa: una tienda que avisa envíos no necesita refunds:write.

ScopePermiteEndpoints
messages:writeEnviar mensajes (texto, archivos, plantillas, botones, listas, ubicaciones y reacciones) y marcar como leído.POST /v1/messages
POST /v1/messages/{id}/read
conversations:readLeer conversaciones y sus mensajes.GET /v1/conversations
GET /v1/conversations/{id}
GET /v1/conversations/{id}/messages
GET /v1/messages/{id}
conversations:writePasar una conversación a una persona, pausar o reanudar el bot y resolverla.POST /v1/conversations/{id}/escalate
POST /v1/conversations/{id}/bot
POST /v1/conversations/{id}/resolve
contacts:readLeer contactos y listas.GET /v1/contacts
GET /v1/contact-lists
contacts:writeCrear contactos y agregarlos a listas.POST /v1/contacts
POST /v1/contact-lists/{id}/members
campaigns:readLeer el estado de una campaña.GET /v1/campaigns/{id}
campaigns:writeCrear y disparar campañas.POST /v1/campaigns
events:readLeer el stream de eventos.GET /v1/events
events:writeRegistrar eventos de tu sistema.POST /v1/events
conversions:writeReportar conversiones para atribuirlas.POST /v1/conversions
charges:writeCobrar con un link de pago.POST /v1/charges
refunds:writeReembolsar pagos.POST /v1/refunds
sales:readLeer el embudo de ventas.GET /v1/sales/funnel
reviews:readLeer reseñas.GET /v1/reviews
reviews:writePedir reseñas.POST /v1/reviews
automations:triggerDisparar flujos.POST /v1/automation-flows/{id}/trigger
owner:writeModo sueño de un espacio personal.GET /v1/owner/sleep
POST /v1/owner/sleep
webhooks:readLeer los webhooks y su registro de entregas.GET /v1/webhooks
GET /v1/webhooks/{id}/deliveries
webhooks:writeCrear, editar y borrar webhooks y reintentar una entrega.POST /v1/webhooks
PATCH /v1/webhooks/{id}
DELETE /v1/webhooks/{id}
POST /v1/webhook-deliveries/{id}/retry
numbers:readVer tus números de WhatsApp de heysteff y el cupo del plan.GET /v1/numbers
GET /v1/numbers/{id}
GET /v1/whatsapp-numbers/{id}
GET /v1/whatsapp-numbers/{id}/business-profile
numbers:writeReservar un número (con su link de conexión), soltar una reserva y pedir el nombre visible.POST /v1/numbers
DELETE /v1/numbers/{id}
POST /v1/numbers/{id}/display-name
PATCH /v1/whatsapp-numbers/{id}/business-profile
flows:readVer tus WhatsApp Flows, su Flow JSON, la vista previa y las respuestas de los clientes.GET /v1/whatsapp-flows
GET /v1/whatsapp-flows/{id}
GET /v1/whatsapp-flows/{id}/json
GET /v1/whatsapp-flows/{id}/preview
GET /v1/whatsapp-flows/responses
flows:writeCrear, cambiar, publicar, deprecar y borrar WhatsApp Flows, subir su Flow JSON y sincronizarlos con Meta.POST /v1/whatsapp-flows
POST /v1/whatsapp-flows/sync
PATCH /v1/whatsapp-flows/{id}
DELETE /v1/whatsapp-flows/{id}
PUT /v1/whatsapp-flows/{id}/json
POST /v1/whatsapp-flows/{id}/publish
POST /v1/whatsapp-flows/{id}/deprecate
calls:readVer el registro de llamadas de WhatsApp y los ajustes de llamadas de un número.GET /v1/calls
GET /v1/whatsapp-numbers/{id}/calling
calls:writeEncender o apagar las llamadas de un número y cambiar su horario.PATCH /v1/whatsapp-numbers/{id}/calling
inbox:embedCrear, ver, cambiar y revocar los tokens de la bandeja embebible.POST /v1/inbox-embeds
GET /v1/inbox-embeds
PATCH/DELETE /v1/inbox-embeds/{id}
logs:readLeer los logs unificados: llamadas a la API, entregas de webhooks y mensajes fallidos (GET /v1/logs).
templates:writeCrear plantillas de WhatsApp (van a revisión de Meta) y borrarlas.POST /v1/templates
DELETE /v1/templates/{name}
customers:readVer tus clientes y los canales que conectaron.GET /v1/customers
GET /v1/customers/{id}
GET /v1/customers/{id}/channels
customers:writeCrear, cambiar y borrar clientes, y generar sus links de conexión.POST /v1/customers
PATCH /v1/customers/{id}
DELETE /v1/customers/{id}
POST /v1/customers/{id}/setup-links
agent:readVer el agente de IA (encendido, modelo, cupo de prueba, keys guardadas solo por sus últimos 4) y sus custom tools.GET /v1/agent
GET /v1/agent/tools
GET /v1/agent/tools/{id}
agent:writeConfigurar el agente, guardar o borrar tu key del proveedor y administrar custom tools.PATCH /v1/agent
PUT /v1/agent/keys
DELETE /v1/agent/keys/{provider}
POST /v1/agent/tools
PATCH /v1/agent/tools/{id}
DELETE /v1/agent/tools/{id}
insights:readLeer los hallazgos de tus conversaciones.GET /v1/insights

Rotar una key sin cortar el servicio#

Desde la lista de keys, Rotar crea un secreto nuevo y deja el anterior funcionando durante un período de gracia (24 horas por defecto). Despliega el secreto nuevo en ese tiempo; al terminar la gracia, el anterior deja de funcionar solo.

IPs permitidas#

Puedes restringir una key a una lista de IPs o rangos CIDR (por ejemplo, 203.0.113.0/24). Una solicitud desde otra IP recibe 403 aunque la key sea válida.

Revocar#

Revocar corta la key en el momento. Hazlo apenas sospeches que se filtró y crea una nueva para la integración.

Errores de autenticación#

StatusCódigoQué pasó
401unauthorizedFalta el header, la key es inválida, venció o fue revocada.
403forbiddenLa key no tiene el scope de la operación o la IP no está permitida.
403workspace_disabledEl workspace está deshabilitado.
429rate_limitedSuperaste el límite de solicitudes de la key.

Buenas prácticas#