Autenticación y claves de API

Toda petición a la API lleva una cabecera de autorización con un token:

Authorization: Bearer <token>

Ese token identifica quién hace la llamada y en qué empresa (tenant) actúa. Sin él, la API responde 401.

Dos tipos de token#

Ambos se envían igual, como Bearer <token>. La diferencia es la duración y el propósito: el JWT es efímero y sirve a la web; la clave de API es duradera y sirve a los agentes.

Claves de API (agl_)#

Las claves de API llevan el prefijo agl_ y se acuñan desde una sesión ya iniciada, en el endpoint:

POST /api/v1/auth/api-keys

Guárdala en un gestor de secretos o variable de entorno; se muestra una sola vez. Por defecto, una clave tiene alcance (scope) *, es decir, puede operar sobre toda la contabilidad de tu empresa, igual que tú desde la web.

Una clave agl_ da acceso completo a tu contabilidad. Trátala como una contraseña: no la publiques, no la incluyas en commits ni en logs. Si se filtra, revócala y acuña otra.

Verificar un token#

Para comprobar que un token es válido y ver la empresa activa, llama a /api/v1/tenants/me:

curl https://api.aikount.com/api/v1/tenants/me \
  -H "Authorization: Bearer agl_tu_clave_aqui"

Una respuesta 200 con los datos de la empresa confirma que el token funciona.

Importante: /auth/me es solo para sesión (login) y rechaza las claves de API. Con una clave agl_, usa siempre /api/v1/tenants/me para verificar el token y conocer el tenant activo.

401 frente a 403#

• 401 Unauthorized — el token falta, es inválido o ha sido revocado. Revisa la cabecera Authorization y que la clave siga activa.
• 403 Forbidden — el token es válido pero no tiene el alcance necesario para esa operación. Con una clave de scope * no deberías verlo salvo en operaciones restringidas.

Los errores llegan como estado HTTP más un cuerpo {"detail": "..."} (ver Convenciones de la API).

Siguiente paso#

Con una clave lista, conecta tu agente en Conectar un agente o por MCP.