Autenticación y alcances

El token

Se manda en cada pedido, en el encabezado Authorization, con el esquema Bearer. No hay cookies ni sesión: un pedido sin el encabezado responde 401.

curl "https://panel.kaptativa.app/api/v1" \
  -H "Authorization: Bearer TU_TOKEN"

• Empieza con kpt_ y sigue con 43 caracteres. Se crea en Administración > API y MCP y se muestra una sola vez.
• Vence cuando lo elegiste al crearlo: en 30 días, en 90 días, en un año, no vence.
• Se revoca desde la misma pantalla y deja de valer en el pedido siguiente.
• Cada cuenta puede tener hasta 20 tokens sin revocar (los vencidos cuentan hasta que se revocan). Usá uno por sistema: así podés revocar uno sin cortar a los demás.
• El mismo token sirve para la API y para el servidor MCP.

De quién es el token

Un token es de la persona que lo creó y actúa con sus permisos, leídos en cada pedido. No hay permisos propios del token: lo que esa persona no puede hacer en el panel, el token tampoco.

• Si a la persona le sacan un permiso, el token lo pierde en el pedido siguiente.
• Si la persona deja la cuenta o la deshabilitan, el token responde 401.
• Lo que el token cambia queda en la Actividad de la cuenta a nombre del token y de su persona.
• El panel guarda 90 días del registro de pedidos de cada token, con la operación, el resultado y cuánto tardó.

Para una integración que tiene que durar, conviene crear el token con un usuario de servicio que tenga solo el perfil que hace falta, y no con el de una persona que puede cambiar de puesto.

Alcances

Los alcances dicen qué módulos puede tocar el token y hasta dónde. Cada uno se escribe modulo:nivel:

El módulo es el primer tramo del nombre de la operación: gestion.cliente.crear es del módulo gestion y, como cambia algo, pide gestion:escritura. Hoy la API tiene operaciones de estos módulos:

La referencia dice qué alcance pide cada operación. En el panel se eligen al crear el token, en Qué puede hacer: Solo ver es *:lectura, Ver y hacer cambios es *:lectura más *:escritura, y Elegir por módulo deja marcar cada módulo como Sin acceso, Ver o Ver y hacer cambios. GET /v1 devuelve los alcances del token con el que se llama.

Los alcances recortan, no dan

Un pedido pasa tres controles, en este orden. Con que falle uno, no se ejecuta:

1. El alcance del token. Si no llega a ese módulo o a ese nivel, responde 403 con el código alcance, y el mensaje dice qué alcance falta. Lo que el token no alcanza tampoco aparece en GET /v1/herramientas.
2. El módulo de la cuenta. Si la cuenta no tiene activo el submódulo de la operación, responde 403 con no_activo.
3. El permiso de la persona. Si su perfil no puede hacerlo, responde 403 con sin_permiso.

Por eso *:escritura en el token de alguien que solo puede ver propiedades sigue sin poder cambiar un precio.

Los tokens de antes

Los tokens creados antes de que existieran los alcances por módulo siguen funcionando igual: uno de Solo ver equivale a *:lectura y uno de Ver y hacer cambios a *:lectura más *:escritura.

Lo que no se ofrece por la API

• Las operaciones que leen datos clasificados como sensibles no están en la API ni en el MCP, tenga el token el alcance que tenga.
• Invitar o habilitar usuarios, pedir un cambio de plan y ver las conexiones con otros servicios se hacen solo desde el panel.
• Una cuenta de demostración no responde por la API.

Cuando el token no pasa