Autenticación y API keys

Todas las rutas del API público de vario requieren una API key válida. Este documento describe cómo obtenerla, cómo usarla en cada request, y cómo gestionarla de forma segura durante el ciclo de vida de tu integración.

1. Autenticación

La API de vario utiliza API keys como mecanismo de autenticación. Cada key tiene el prefijo vario_ y se incluye en el header Authorization de cada request como un Bearer token.

Authorization: Bearer vario_TU_API_KEY

Ejemplo con curl:

curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer vario_TU_API_KEY"

Cualquier request sin este header, o con una key inválida, inactiva o expirada, recibe una respuesta 401.

2. Cómo obtener una API key

Registro en el portal

Regístrate en el portal de developers de vario enviando tu email corporativo y el nombre de tu organización. Al completar el registro, el sistema genera automáticamente tu primera API key y la muestra una sola vez en pantalla. También se envía al email registrado.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Firma Forense LATAM"
  }'

Response 201:

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "docs_note": "$0.150 per credit. Pricing is subject to change."
}

Al registrarte recibes 250 créditos gratuitos para explorar la API.

Keys adicionales

Una vez registrado, puedes crear keys adicionales desde el portal o vía API. Esto es útil para separar credenciales por caso de uso, equipo o proyecto.

curl -X POST https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integración CADE matter 2026",
    "scopes": ["analyze:run", "playbooks:list"],
    "expires_at": "2027-06-01T00:00:00Z"
  }'

Response 201:

{
  "key_id": "uuid",
  "key": "vario_newXXX...ABC",
  "name": "Integración CADE matter 2026",
  "scopes": ["analyze:run", "playbooks:list"],
  "expires_at": "2027-06-01T00:00:00Z",
  "created_at": "2026-06-02T10:00:00Z",
  "warning": "Store this key immediately. It will not be shown again."
}

El campo key solo aparece en el response de creación. Después de eso, el portal muestra únicamente un key_hint (primeros y últimos caracteres) para identificación visual — el token completo no se puede recuperar.

3. Seguridad de la key

Una API key de vario otorga acceso a los endpoints de tu tenant. Trátala como una contraseña.

Buenas prácticas:

• Usa variables de entorno para inyectar la key en tu aplicación. Nunca la escribas directamente en el código fuente.
• Nunca incluyas una API key en código frontend (JavaScript del navegador, aplicaciones móviles). Las keys son credenciales server-side.
• Nunca subas una key a un repositorio público (GitHub, GitLab, etc.). Si lo hiciste por error, revócala de inmediato y genera una nueva.
• Usa keys separadas por contexto: una para staging, otra para producción, otra por integración de tercero si corresponde.

# Correcto: variable de entorno
export VARIO_API_KEY="vario_TU_API_KEY"

curl https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Scopes

Cada key tiene uno o más scopes que limitan los endpoints que puede invocar:

Si un request usa una key sin el scope requerido, la API retorna 403 INSUFFICIENT_SCOPE. Al crear una key, otorga solo los scopes necesarios para ese caso de uso.

4. Gestión de keys desde el portal

El portal de developers muestra todas las API keys activas de tu tenant. Desde allí puedes:

Listar keys activas

curl https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_TU_API_KEY"

Response 200:

[
  {
    "key_id": "uuid",
    "name": "Integración CADE matter 2026",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-02T09:00:00Z",
    "expires_at": "2027-06-01T00:00:00Z",
    "created_at": "2026-06-02T10:00:00Z"
  }
]

El campo key_hint muestra los primeros y últimos caracteres del token para que puedas identificar cada key visualmente sin exponer el valor completo.

Revocar una key

Cuando una key ya no se usa, o si sospechas que fue comprometida, revócala con su key_id. La revocación es inmediata e irreversible.

curl -X DELETE https://api.vario.lat/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer vario_TU_API_KEY"

Response: 204 No Content

La revocación desactiva la key sin borrar su registro. El historial de uso se preserva en el audit trail del tenant.

5. Rotación de keys

La rotación genera una nueva key con los mismos scopes que la actual y revoca la anterior en una sola operación atómica.

curl -X POST https://api.vario.lat/api/public/api-keys/rotate \
  -H "Authorization: Bearer vario_TU_API_KEY"

Response 200:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again."
}

Cuándo rotar:

• Sospecha de que la key fue expuesta (repositorio público, log visible, captura de tráfico).
• Rotación periódica como parte de la política de seguridad de tu organización.
• Cambio de equipo responsable de la integración.

Qué pasa con las llamadas en vuelo al rotar:

La key anterior queda inactiva en el momento en que se ejecuta el endpoint de rotación. Cualquier request en tránsito que use la key anterior recibirá 401 INVALID_API_KEY. Configura tu cliente para reintentar con la nueva key inmediatamente después de recibirla.

6. Rate limits por key

Cada API key tiene límites de tasa según el plan del tenant. Al superar el límite, la API retorna 429 RATE_LIMIT_EXCEEDED con el header Retry-After indicando los segundos hasta el próximo slot disponible.

Los límites específicos por plan están documentados en Errores y rate limits.

7. Ejemplo completo de autenticación

# Registrar cuenta y obtener key inicial
curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Firma Forense LATAM"
  }'

# Guardar la key del response como variable de entorno
export VARIO_API_KEY="vario_xbGhABC123...WXYZ"

# Verificar acceso: listar playbooks disponibles
curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer $VARIO_API_KEY"

# Enviar un texto para análisis
curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Acordamos no bajar de $450 la unidad.",
    "playbook": "price_fixing",
    "language": "es",
    "mode": "fast"
  }'

Errores de autenticación