Constaia

Autenticación

Autentica tus llamadas a la API de Constaia con claves Bearer ck_live_ y ck_test_, dónde crearlas y revocarlas, y por qué nunca van al navegador.

Todas las llamadas a https://api.constaia.com/v1 (salvo el catálogo público de tipos de documento y las descargas firmadas de exportaciones) se autentican con una clave secreta en la cabecera Authorization:

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Formato de las claves

PrefijoModoQué hace
ck_test_…TestProveedor simulado con respuestas deterministas según el nombre del fichero. Gratis, livemode: false. Ver Modo test.
ck_live_…LiveAnaliza los documentos de verdad y consume créditos. livemode: true.
pk_test_… / pk_live_…Test / LiveClave publicable para el navegador: solo sube documentos a una sesión que crea tu servidor, y solo desde los dominios que autorices.

Después del prefijo van entre 24 y 64 caracteres alfanuméricos. El modo lo decide la clave, no un parámetro de la petición: el mismo código funciona en test y en live cambiando solo la variable de entorno.

Crear y revocar claves

Las claves se gestionan en el panel, en Desarrolladores → Claves de API:

  • Al registrarte se crea una clave de test para que puedas empezar sin configurar nada.
  • Para crear una clave live necesitas haber confirmado tu email. Si no, el panel responde con el error email_not_verified. Si te registraste con Google o GitHub, tu email ya está verificado.
  • Cada clave se muestra una sola vez, al crearla. Cópiala en ese momento a tu gestor de secretos.
  • Constaia guarda solo un hash SHA-256 de la clave: no podemos recuperarla ni volver a enseñártela. Si la pierdes, crea otra y revoca la antigua.
  • Una clave revocada deja de funcionar al instante y devuelve 401 invalid_api_key.

Para rotar claves sin cortes (crear la nueva, desplegar, revocar la vieja) sigue los pasos de Seguridad.

Errores de autenticación

HTTPcodeCuándo
401missing_api_keyFalta la cabecera Authorization: Bearer … o no tiene ese formato.
401invalid_api_keyLa clave no tiene el formato ck_live_/ck_test_ (o pk_live_/pk_test_), no existe o está revocada.
403secret_key_in_browserUna clave secreta (ck_…) usada desde un navegador.
403publishable_key_not_allowedUna clave publicable (pk_…) en una ruta que no es la subida de una sesión.
403origin_not_allowedUna clave publicable desde un dominio que no está en su lista.
403account_suspendedLa cuenta está suspendida.
Respuesta 401
{
  "error": {
    "type": "authentication",
    "code": "missing_api_key",
    "message": "Falta la cabecera Authorization: Bearer <api_key>.",
    "request_id": "req_01M3PD48ARCDHXGT0XECMARCPD"
  }
}

Todos los errores siguen este formato. Consulta Errores.

La clave vive en tu servidor

Nunca en el navegador ni en una app móvil

Una clave ck_live_ o ck_test_ da acceso a tu cuenta y a tus créditos. No la pongas en código de frontend, en una app móvil, en un repositorio ni en variables NEXT_PUBLIC_*/VITE_*. Tu frontend o tu app envía el fichero a tu backend, y tu backend llama a Constaia.

La API tiene CORS abierto en /v1, pero eso no cambia la regla: el SDK de JavaScript lanza el error secret_key_in_browser si detecta una clave secreta en un navegador, la API la rechaza con 403 secret_key_in_browser si llega desde una página de otro origen, y el widget rechaza cualquier atributo que parezca una clave secreta.

Claves publicables (pk_…)

Si quieres que el navegador suba el documento directamente a Constaia, sin pasar por tu servidor, usa una clave publicable. Esa sí puede ir en el código de tu web, porque solo permite una cosa: subir documentos a una sesión que tu backend crea con la clave secreta (POST /v1/sessions), desde los dominios que autorices (1–20, app.tuweb.com, *.tuweb.com y, en test, localhost:3000).

  • Se crean en Desarrolladores → Claves de API, con el tipo Publicable, y se muestran una sola vez.
  • Solo sirven para POST /v1/analyze con el client_secret de una sesión; cualquier otra ruta devuelve 403 publishable_key_not_allowed.
  • Las opciones de análisis salen de la sesión y su plantilla: el navegador no puede cambiar expect ni checks.

Referencia en Sesiones y claves publicables y guía en Integración solo frontend.

Variable de entorno CONSTAIA_API_KEY

Guarda la clave en CONSTAIA_API_KEY. Los SDK de JavaScript, PHP y Python y el servidor MCP la leen automáticamente si no les pasas una clave.

.env
CONSTAIA_API_KEY=ck_test_...

Ejemplos mínimos

Todos llaman a GET /v1/balance, que no consume créditos.

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Cada respuesta lleva la cabecera X-Request-Id: req_…. Guárdala en tus logs e inclúyela si nos escribes por un problema.

Siguientes pasos

En esta página