Ir al contenido

Claves y permisos

Cómo crear y revocar claves de API, qué permisos elegir y qué datos puede leer cada clave.

Cada petición a la API lleva una clave. Tú mismo creas tus claves en el portal de Bookline, y cada una lee los datos que tú puedes ver, limitados a los permisos que le das al crearla.

Las claves se crean en el portal, en el menú Administración → Claves de API. La opción solo aparece si tu usuario puede leer al menos un cliente.

  1. Haz clic en Crear clave, ponle un nombre (por ejemplo, la herramienta que la va a usar), elige sus permisos y la caducidad.
  2. Copia la clave en ese momento. Empieza por bk_live_ y se muestra solo una vez: Bookline guarda únicamente un hash y no puede volver a mostrarla.
  3. Guárdala en el gestor de secretos de tu herramienta, nunca en el código ni en una hoja compartida.
Regla Valor
Opciones de caducidad Sin caducidad, 90 días, 1 año (por defecto: 1 año)
Claves activas por usuario 5
Claves de cuenta (de todo el cliente) 10 por cliente

Para desactivar una clave, haz clic en Revocar junto a ella, en la misma página de Claves de API.

Cada clave está ligada a la persona que la creó y sigue sus permisos actuales. Si cambia tu rol o se elimina tu usuario, la clave deja de funcionar.

Cada clave lleva unos permisos que deciden a qué rutas puede llamar: <ámbito>:read para leer un ámbito, <ámbito>:write para cambiarlo. Los eliges al crear la clave y no se pueden cambiar después: si necesitas otros, crea una clave nueva y revoca la anterior. Si no eliges ninguno, la clave tiene metrics:read.

Cada ámbito de la API tiene un permiso de lectura y, donde la API puede cambiarlo, uno de escritura:

Ámbito Lectura Escritura Rutas
Métricas metrics:read /v1/metrics/*
Locales venues:read venues:write /v1/venues (la lista también acepta metrics:read)
Llamadas calls:read /v1/calls
Chats chats:read /v1/chats
Reservas bookings:read /v1/bookings
Contactos contacts:read contacts:write /v1/contacts
Agentes bots:read bots:write /v1/agents
Bases de conocimiento knowledge_bases:read knowledge_bases:write /v1/knowledge-bases
Notificaciones (campañas) notifications:read notifications:write /v1/campaigns
Números de teléfono numbers:read /v1/numbers
Integraciones integrations:read /v1/integrations
Usuarios (equipo) users:read users:write /v1/users
Facturación billing:read /v1/billing/*

Llamar a una ruta sin su permiso da 403 insufficient_scope. Todas las rutas, con el permiso que necesita cada una, están en Endpoints.

Al marcar la escritura de un ámbito se marca también su lectura, y una clave con permiso de escritura siempre lee ese ámbito: para cambiar algo antes hay que leerlo (consulta Escribir datos). Así, una clave con contacts:write lee toda tu agenda de contactos, y una con users:write todo tu equipo: en los dos casos, datos personales.

Envía la clave en la cabecera apikey en cada petición. Solo /v1/docs y /v1/openapi.json funcionan sin clave.

apikey: bk_live_...

Si falta la clave o no existe, la respuesta es 401 invalid_api_key. Una clave solo funciona en /v1.

Lo que lee una clave se decide en cada petición según los permisos actuales de su propietario en el portal:

Tu acceso Qué lee la clave customer_id
Un cliente, completo Ese cliente Opcional
Varios clientes Cualquiera de ellos Obligatorio (400 customer_ambiguous si falta)
Algunos locales de un cliente Ese cliente, solo esos locales Opcional si es tu único cliente
Clave de cuenta Su propio cliente Opcional; otro cliente da 403
Solo la actividad de un cliente Las métricas, llamadas y chats de ese cliente; nada más Opcional si es tu único cliente

Indicar un cliente que la clave no puede leer da 403 insufficient_scope.

Una clave solo cambia datos si tiene el permiso de escritura del ámbito y el acceso de su propietario en el portal permite el cambio: ADMIN, o el nivel de la acción (CREATE, UPDATE o DELETE). El acceso solo a la actividad de un cliente nunca escribe. Una clave de cuenta escribe lo que permiten sus permisos en su propio cliente. El acceso del equipo tiene sus propias reglas: consulta Equipo.

  • Sin venue_ids, recibes todos los locales que puedes ver.
  • Con venue_ids, cada id debe ser de un local que puedes ver; si no, 403 insufficient_scope.
  • GET /v1/venues lista los locales que tu clave puede leer, con sus ids.
  • Los locales, las métricas, las llamadas, los chats, las reservas, los agentes y las bases de conocimiento se limitan a esos locales y a sus agentes.
  • Los contactos, las campañas, los números de teléfono, las integraciones, el equipo y la facturación son de todo el cliente: una clave limitada a algunos locales recibe 403 insufficient_scope, y también al crear una base de conocimiento.