Autenticación

Cabecera Authorization

Envía el token en todas las peticiones con la cabecera Authorization:

GET https://app.bm.consulting/api/v1/contacts HTTP/1.1
Authorization: Bearer bmc_live_…

Los tokens empiezan por bmc_live_. La API solo se sirve por HTTPS; no envíes el token por canales sin cifrar ni lo incluyas en la URL.

Qué comprueba la API, y en qué orden

1. Que el token exista, esté activo, no esté revocado y no haya caducado. Si no, responde 401.
2. Que la ruta admita tokens ligados a una cuenta. Si no, responde 403.
3. Que alguno de los permisos del token cubra el que exige la ruta. Si no, responde 403 con required_permission.
4. Que la IP de origen esté en la lista de IPs permitidas del token, si la tiene. Si no, responde 403.
5. Que no se superen los límites de uso. Si no, responde 429 (Límites de uso).

Alcance: empresas y grupos

Al crear el token, en Empresas y grupos, eliges de qué empresas verá datos (paso a paso):

• Cuenta principal: siempre una. Sus límites por minuto y su cuota mensual son los que gasta el token.
• Otras empresas: las que también administras como titular o administrador y tienen el acceso a la API activado.
• Grupos enteros: solo si los eliges. Un grupo incluye todas sus filiales, también las que se den de alta más adelante. Elegir una empresa de un grupo no añade el resto.

El alcance se recalcula en cada petición. Si quien creó el token deja de ser titular o administrador de una empresa, el token deja de verla; si la pierde en la cuenta principal, el token deja de funcionar y la API responde 401. Estos cambios pueden tardar hasta 60 segundos en aplicarse. La lista de empresas que alcanza hoy un token la devuelve GET /auth/whoami.

Una conexión MCP hecha con OAuth (por ejemplo, desde Claude o ChatGPT) alcanza una sola empresa, la que eliges al autorizar. Para un agente que trabaje con varias empresas, usa un token bmc_live_… con esas empresas.

Ciclo de vida del token

Creación

Se crea en el área de cliente, en Desarrolladores › Credenciales. El token completo se muestra una sola vez; BMC conserva solo una huella que no permite recuperarlo. Si lo pierdes, rótalo o crea otro.

Rotación

Rotar un token sustituye su valor por otro nuevo; el anterior deja de servir. Actualiza la integración con el valor nuevo. Rota los tokens de forma periódica y siempre que sospeches que se han expuesto.

Interruptor

Cada token se puede desactivar y volver a activar sin perder su configuración. Mientras está desactivado, la API responde 401.

Revocación

Revocar un token es definitivo: deja de funcionar y no se puede reactivar. Crea uno nuevo si hace falta.

Caducidad

Puedes fijar una fecha de caducidad al crear el token. Pasada esa fecha, la API responde 401. Para integraciones temporales, usa la caducidad más corta que sirva.

Acceso a la API de la empresa

Si BMC desactiva el acceso a la API de una empresa, el área de cliente deja de mostrar la sección Desarrolladores y no se pueden crear, editar ni rotar tokens. Hoy, los tokens y las conexiones que ya existían siguen funcionando hasta que caducan o se revocan. Si quieres cortarlos, desactívalos o revócalos tú antes, o pide a BMC que lo haga.

Direcciones IP permitidas

Un token puede limitarse a una lista de direcciones IP o rangos CIDR, en IPv4 o IPv6 (por ejemplo, 203.0.113.10 o 203.0.113.0/24). Con la lista vacía, el token funciona desde cualquier IP. Con una lista, las peticiones desde otra IP reciben 403.

BMC evalúa la IP con la que la petición llega a su infraestructura. Si tu servidor sale a Internet a través de un proxy o una puerta de enlace NAT, añade la dirección de salida de ese proxy, no la interna.

Las conexiones MCP hechas con OAuth no llevan lista de IPs: se controlan con el rol, la caducidad y el interruptor de la conexión (Servidor MCP). Un token bmc_live_… con lista de IPs no sirve en el servidor MCP, porque el servidor MCP llama a la API desde la infraestructura de BMC y esa llamada se rechaza. Para usar un token con el servidor MCP, deja la lista vacía.

OAuth para el servidor MCP

El token Bearer es la vía para integraciones de servidor a servidor. Para conectar un asistente o cliente MCP (Claude o ChatGPT, por ejemplo) no hace falta copiar ningún token: el servidor MCP usa OAuth 2.1 con PKCE. Quien conecta inicia sesión en BMC, elige la empresa y el rol, y la conexión aparece en Desarrolladores › API y MCP › Credenciales como una credencial de tipo MCP. El token de acceso dura 1 hora y el de renovación 30 días; los gestiona el cliente. Detalle en Servidor MCP y, paso a paso por asistente, en Conecta tu IA.

Datos personales enmascarados

Un token puede leer un recurso (contactos, trabajadores, cuentas bancarias) sin ver los datos personales que contiene. Si en el token no está marcada la casilla Puede ver datos personales, los recursos marcados como tales en el catálogo devuelven enmascarados:

Marca esa casilla solo en los tokens de integraciones que lo necesiten de verdad. No es un permiso del catálogo: es una opción de cada token.

Buenas prácticas

• Un token por integración, con un nombre que diga para qué sirve. Así puedes revocar una sin afectar a las demás.
• Concede el mínimo de permisos: empieza por Leer y evita el nivel Full si no es imprescindible.
• Fija una caducidad y rota los tokens de forma periódica.
• Limita el token a las IPs de tus servidores cuando sean fijas.
• Guarda el token en un gestor de secretos o una variable de entorno; nunca en el código, en registros ni en repositorios.
• Si un token se expone, revócalo de inmediato y crea otro.