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
| Prefijo | Modo | Qué hace |
|---|---|---|
ck_test_… | Test | Proveedor simulado con respuestas deterministas según el nombre del fichero. Gratis, livemode: false. Ver Modo test. |
ck_live_… | Live | Analiza los documentos de verdad y consume créditos. livemode: true. |
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 la sección API keys:
- 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. - 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
| HTTP | code | Cuándo |
|---|---|---|
| 401 | missing_api_key | Falta la cabecera Authorization: Bearer … o no tiene ese formato. |
| 401 | invalid_api_key | La clave no tiene el formato ck_live_/ck_test_, no existe o está revocada. |
{
"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 en un navegador, y el widget rechaza cualquier atributo que parezca una clave. Las claves publicables para navegador aún no existen.
Próximamente
Claves publicables (de navegador) con permisos limitados.
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.
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
LangChain y LlamaIndex
Envuelve Constaia como herramienta de LangChain (JS y Python) y de LlamaIndex para que tus agentes validen documentos y reciban un veredicto claro.
POST /v1/analyze
Referencia completa de POST /v1/analyze: formas de envío, todas las opciones y checks, objeto analysis campo a campo, códigos de estado y ejemplos.