Autenticación
Claves de API y autenticación
Cada llamada lleva una clave de tu cuenta de desarrollador en la cabecera Authorization. Aquí, cómo se crea, cómo se guarda, cómo se rota y qué errores da.
La clave de API
Una clave pertenece a tu cuenta de desarrollador, no a una persona ni a un despacho: el uso y el saldo se miden a la cuenta. Puedes tener varias claves (una por integración, por ejemplo) y revocar cada una por separado. Tienen la forma iuris_sk_….
- Se crea desde el panel de desarrollador (developers.jurilia.com/desarrollador).
- Se enseña en claro una sola vez, al crearla. No hay forma de volver a leerla: si la pierdes, se revoca y se crea otra.
- El panel muestra de cada clave su nombre, cuándo se creó, cuándo se usó por última vez y cuántas llamadas ha hecho en los últimos 30 días.
- Una clave de despacho de la aplicación (Configuración › API) NO vale en /v1/dev: da 401 con el código
clave_no_es_de_desarrollador.
La cabecera Authorization
La clave va SIEMPRE en la cabecera Authorization, como token de portador (bearer). No hay otro método: nunca en la URL ni en el cuerpo de la petición.
Authorization: Bearer iuris_sk_…curl
curl https://app.jurilia.com/v1/dev/ping \
-H "Authorization: Bearer TU_CLAVE"Python
import os, requests
clave = os.environ["JURILIA_API_KEY"] # nunca la escribas en el código
r = requests.get("https://app.jurilia.com/v1/dev/ping", headers={"Authorization": f"Bearer {clave}"})JavaScript
const clave = process.env.JURILIA_API_KEY; // nunca la escribas en el código
const r = await fetch("https://app.jurilia.com/v1/dev/ping", { headers: { Authorization: `Bearer ${clave}` } });Errores de autenticación
| Estado | Código | Qué significa | Qué hacer |
|---|---|---|---|
| 401 | no_autenticado | Falta la cabecera Authorization. | Envía Authorization: Bearer TU_CLAVE. |
| 401 | clave_invalida | La clave no existe, está mal copiada o ha sido revocada. | Revisa que la has copiado entera; si se revocó, crea otra. |
| 401 | clave_no_es_de_desarrollador | Es una clave de un despacho de la aplicación. | Crea una clave en tu cuenta de desarrollador. |
| 403 | clave_ip_no_permitida | La clave lleva una lista de IPs/redes y la llamada viene de fuera. | Llama desde una IP permitida o cambia la lista. |
| 429 | demasiadas_peticiones | Superaste las 120 llamadas por minuto de la clave. | Espera los segundos de la cabecera Retry-After. |
Rotar una clave sin cortes
Rotar una clave es sustituirla por otra sin dejar de servir. Como revocar es inmediato (la clave deja de funcionar al instante y no se puede deshacer), el orden importa:
1. Crea la clave nueva
Con otro nombre («Integración contable 2026-10»). Las dos funcionan a la vez.
2. Cámbiala en tu integración
Despliega la configuración con la clave nueva.
3. Comprueba que la antigua ya no se usa
En el panel, mira su «último uso» y sus llamadas de los últimos 30 días.
4. Revoca la antigua
Desde el panel. Si algo la seguía usando, empezará a recibir 401.
Si una clave se filtra
Revócala en el panel de inmediato y crea otra: no hace falta esperar a ningún paso previo.
Restricción por IP o red (CIDR)
La API admite que una clave lleve una lista blanca de IPs o redes (formato CIDR, IPv4 o IPv6): con la lista puesta, una llamada desde fuera da 403 clave_ip_no_permitida aunque la clave sea válida. Una clave sin lista —el valor por defecto— vale desde cualquier dirección.
Pendiente: configurarla desde el panel
El panel de desarrollador todavía NO permite poner o quitar la lista de IPs: toda clave de desarrollador nace sin restricción. La API ya la aplica; falta el control en el panel.
Cómo guardar la clave
- En una variable de entorno o en un gestor de secretos, nunca en el código fuente ni en un repositorio.
- Sólo desde tu servidor: no la pongas en una aplicación web, móvil o de escritorio que distribuyas, donde cualquiera podría extraerla.
- Una clave por integración, para poder revocar una sin parar las demás.