Desarrolladores · Autenticación

API keys, el header y los errores de acceso.

Todo lo que necesitás para autenticar una llamada a la API REST: cómo se genera la key, cómo se manda, qué plan habilita qué, y cómo resolver un 401/403.

La consola de esta sección no usa API key. Corre con tu sesión de navegador (cookie same-origin) y eso funciona en cualquier plan, incluido el gratuito — el requisito de plan Ultimate/Team/Enterprise de acá abajo es sólo para cuando vos llamás a la API desde tu propio backend con una key.

1. Generar tu API key

Se genera desde la web, logueado, en /account/api-keys. El valor en texto plano se muestra una sola vez — copialo antes de cerrar la pantalla, no queda guardado en ningún lado que puedas volver a ver. Vence al año por defecto y podés tener hasta 10 keys activas por cuenta (revocá una para crear otra).

Podés generar una key en cualquier plan, incluido el gratuito — lo que varía por plan es qué canales podés usar con ella (ver punto 3).

2. El header

Cada llamada autenticada manda la key en Authorization: Bearer — nada de query params ni de otro header custom:

bash

curl -H "Authorization: Bearer alm_..." \
  https://api.almanac.ar/v1/balance

Guardala en una variable de entorno, nunca hardcodeada en el repo. Si se filtra, revocala en /account/api-keys y generá una nueva — no hay forma de “rotar” una key existente, sólo de reemplazarla.

Una key habilita todo lo que tu cuenta puede hacer. No hay keys de sólo lectura ni acotadas a un canal: la misma key que usás para conectar el MCP puede generar informes, y esos informes consumen tu cupo. Tratala como una credencial de la cuenta entera, no como un token de lectura — sobre todo si se la vas a dar a un tercero o la vas a dejar en un sistema que no controlás.

3. Qué plan habilita qué

Público, sin key: GET /v1/prices y GET /v1/openapi.json no piden Authorization.
API REST (con tu key): POST/GET /v1/reports, GET /v1/reports/{id}, GET /v1/reports/quote y GET /v1/balance requieren plan Ultimate, Team o Enterprise cuando se llaman con API key. Mirá Planes y precios.
Sesión de navegador (misma cuenta): Sin ese gate de plan: cualquier usuario logueado puede generar/consultar informes desde la web (o desde la consola de esta doc). El gate de plan es sólo para el canal API.

4. Errores de autenticación más comunes

Status	error	Cuándo pasa	Solución
401	unauthenticated	No mandaste el header Authorization, o la key está mal escrita, vencida o revocada.	Generá una key en /account/api-keys y mandá el header exacto: Authorization: Bearer alm_<key>.
403	account_suspended	La cuenta está suspendida.	Escribinos a contacto@almanac.ar.
403	channel_disabled	Tu plan no tiene habilitado el canal API REST (api_rest_enabled). Aplica a /v1/reports, /v1/reports/quote, /v1/balance — no a los endpoints públicos.	Actualizá a Ultimate, Team o Enterprise. La respuesta trae upgrade_url con el link directo a /pricing.
403	forbidden	Llamaste con cookie de sesión (no con API key) desde un origen no confiable — protección CSRF que sólo aplica al canal de sesión.	No aplica si autenticás con tu API key. Si estás probando desde la web logueado, hacé la llamada desde el propio dominio de Almanac o usá una key.

Todo error de la API viene con la forma { error, message } (más campos según el caso — upgrade_url en channel_disabled, Retry-After en los 429). El contrato completo, con cada error tipado, está en Errores o en /v1/openapi.json.