Gestión de cuenta y signup

Esta página cubre el ciclo completo de gestión de cuenta para la API de vario: desde el registro inicial hasta la rotación de credenciales. Todos los ejemplos usan la URL base de producción https://api.vario.lat.

1. Registro de cuenta API

`POST /api/public/api-signup`

Crea una cuenta API-only con 250 créditos de prueba gratuitos. No requiere autenticación previa. Una vez creada la cuenta, la API key se envía también por email.

Autenticación: ninguna (endpoint público, rate-limitado a 5 solicitudes/min).

Parámetros del request:

Campo	Tipo	Requerido	Descripción
`email`	`string`	Sí	Email corporativo. No se aceptan dominios de correo gratuito.
`name`	`string`	Sí	Nombre completo del solicitante.
`organization`	`string`	Sí	Nombre de la organización.

Ejemplo de request:

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

Ejemplo de response 201:

{
  "api_key": "vario_xbGhABC123...WXYZ",
  "credits_balance": 250,
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced."
}

ℹ

Importante: la api_key se muestra una sola vez en este response. Guárdala de inmediato en un gestor de secretos. vario no almacena el valor completo de la key — si la pierdes, debes revocarla y generar una nueva.

Errores posibles:

HTTP	Código	Condición
`409`	`email_already_registered`	El email ya tiene una cuenta registrada.
`422`	`VALIDATION_ERROR`	Email de dominio gratuito, formato inválido, o campo faltante.
`429`	`RATE_LIMIT_EXCEEDED`	Se superaron las 5 solicitudes por minuto.

2. Información de la cuenta

`GET /api/v1/api-portal/me`

Retorna el estado actual de la cuenta: identidad, tipo de cuenta, estado de suscripción y balance de créditos.

Autenticación: Authorization: Bearer vario_TU_API_KEY o SSO (sesión del portal web).

Ejemplo de request:

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

Ejemplo de response 200:

{
  "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Ana Beatriz Souza",
  "organization": "Firma Forense LATAM",
  "account_type": "api_only",
  "subscription_status": "trial",
  "credits_balance": 247,
  "api_keys_count": 1
}

Campos del response:

Campo	Tipo	Descripción
`tenant_id`	`string` (UUID)	Identificador único del tenant. Inmutable.
`email`	`string`	Email asociado a la cuenta.
`name`	`string`	Nombre del titular de la cuenta.
`organization`	`string`	Nombre de la organización registrada.
`account_type`	`string`	`"api_only"` para cuentas sin seats. `"saas"` para cuentas con suscripción SaaS.
`subscription_status`	`string`	`"trial"` / `"active"` / `"past_due"` / `"canceled"`.
`credits_balance`	`integer`	Créditos disponibles en el balance actual.
`api_keys_count`	`integer`	Número de API keys activas asociadas a la cuenta.

3. Listar API keys

`GET /api/v1/api-portal/keys`

Retorna todas las API keys activas de la cuenta. El valor completo de cada key no se incluye en el response — solo se muestra un key_hint para identificación visual.

Autenticación: Authorization: Bearer vario_TU_API_KEY o SSO.

Ejemplo de request:

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

Ejemplo de response 200:

[
  {
    "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Producción — CADE matter 2026",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-01T18:45:00Z",
    "created_at": "2026-05-15T10:00:00Z",
    "expires_at": null
  },
  {
    "key_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "CI pipeline",
    "key_hint": "vario_yZaB...VWXY",
    "scopes": ["analyze:run"],
    "is_active": true,
    "last_used_at": "2026-06-02T08:12:00Z",
    "created_at": "2026-05-20T14:30:00Z",
    "expires_at": "2027-05-20T00:00:00Z"
  }
]

Campos del response:

Campo	Tipo	Descripción
`key_id`	`string` (UUID)	Identificador único de la key. Se usa para revocarla.
`name`	`string`	Etiqueta descriptiva asignada al crear la key.
`key_hint`	`string`	Primeros 10 y últimos 4 caracteres del token. Solo para identificación visual.
`scopes`	`list[string]`	Permisos habilitados en esta key.
`is_active`	`boolean`	`false` si la key fue revocada.
`last_used_at`	`string` (ISO 8601)	Última vez que esta key realizó un request exitoso. `null` si nunca fue usada.
`created_at`	`string` (ISO 8601)	Fecha de creación.
`expires_at`	`string` (ISO 8601) \| `null`	Fecha de expiración configurada, o `null` si no expira.

4. Crear API key adicional

`POST /api/v1/api-portal/keys`

Genera una nueva API key para la cuenta. Solo disponible vía SSO (sesión del portal web) — no se puede invocar con una API key existente como credencial.

Autenticación: SSO (sesión activa en el portal web).

Parámetros del request:

Campo	Tipo	Requerido	Descripción
`name`	`string`	Sí	Etiqueta para identificar esta key.
`scopes`	`list[string]`	No	Valores válidos: `"analyze:run"`, `"playbooks:list"`. Default: todos.
`expires_at`	`string` (ISO 8601)	No	Fecha de expiración. Si se omite, la key no expira.

Ejemplo de response 201:

{
  "key_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "key": "vario_newXYZ789...ABCD",
  "name": "CI pipeline",
  "scopes": ["analyze:run"],
  "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."
}

5. Revocar API key

`DELETE /api/v1/api-portal/keys/{key_id}`

Revoca una API key de forma permanente e inmediata.

Autenticación: Authorization: Bearer vario_TU_API_KEY o SSO.

curl -X DELETE https://api.vario.lat/api/v1/api-portal/keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer vario_TU_API_KEY"

Response 204 No Content — sin body.

ℹ

Efecto inmediato: no hay período de gracia. Cualquier request autenticado con la key revocada falla con 401 desde el momento de la revocación.

6. Rotación rápida de API key

`POST /api/public/api-keys/rotate`

Invalida la API key actual y genera una nueva con los mismos scopes en una sola operación. Diseñado para respuesta a incidentes de seguridad.

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

Ejemplo de response 200:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again. The previous key is now invalid."
}

ℹ

Secuencia de rotación recomendada:

Ejecutar POST /api/public/api-keys/rotate.
Guardar la nueva key de inmediato.
Actualizar la variable de entorno en todos los servicios que usaban la key anterior.
Verificar que los servicios respondan correctamente con la nueva key.

Buenas prácticas de gestión de credenciales

Nunca incluir la API key en el código fuente. Usar variables de entorno o un gestor de secretos.
Una key por entorno. Crear keys separadas para desarrollo, staging y producción.
Usar name descriptivo. Facilita identificar qué servicio usa cada key.
Configurar expires_at para keys de corta vida. Útil para integraciones temporales.
Ante sospecha de compromiso: usar POST /api/public/api-keys/rotate de inmediato.

Flujo completo de onboarding

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

# Balance inicial: 250 créditos de prueba

# Paso 2: Verificar la cuenta
curl https://api.vario.lat/api/v1/api-portal/me \
  -H "Authorization: Bearer vario_TU_API_KEY"

# Paso 3: Ver las keys activas
curl https://api.vario.lat/api/v1/api-portal/keys \
  -H "Authorization: Bearer vario_TU_API_KEY"