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.
Crear una clave
Sección titulada «Crear una clave»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.
- Haz clic en Crear clave, ponle un nombre (por ejemplo, la herramienta que la va a usar), elige sus permisos y la caducidad.
- 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. - 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 |
Revocar una clave
Sección titulada «Revocar una clave»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.
Permisos (scopes)
Sección titulada «Permisos (scopes)»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.
Qué lee cada clave
Sección titulada «Qué lee cada clave»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.
Qué puede cambiar cada clave
Sección titulada «Qué puede cambiar cada clave»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.
Acceso limitado a algunos locales
Sección titulada «Acceso limitado a algunos locales»- 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, 403insufficient_scope. GET /v1/venueslista 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.
Relacionado
Sección titulada «Relacionado»- API de Bookline: primeros pasos con tu clave.
- Endpoints: todas las rutas y su permiso.
- Escribir datos: versiones, reintentos y el límite de escritura.
- Errores y límites de uso: qué significa cada código de error.
