Autenticación y permisos

Cómo funciona la llave, qué puede hacer, cómo se rota y qué hacer si se filtra.

Toda petición a /v1 va con la llave en la cabecera:

Authorization: Bearer vk_live_a1b2c3...

Sin ella, o con una inválida, la respuesta es 401. No decimos cuál de las razones fue —inválida, revocada, vencida o desde una IP no permitida— porque decirlo le regala información a quien esté probando llaves a ciegas.

Formato del token

Parte	Ejemplo	Qué es
Prefijo	`vk_live_`	`vk_test_` fuera de producción, para no mezclar ambientes
Secreto	43 caracteres	256 bits de entropía

En nuestra base solo guardamos el SHA-256 del token. Nunca el secreto, nunca en logs.

Los tres candados

Lo que una llave puede hacer es la intersección de tres cosas:

permiso efectivo = permisos de la llave  ∩  tu plan  ∩  los negocios de la llave

Permisos de la llave (scopes). Los marcas al crearla. Sin el permiso, 403 SCOPE_REQUIRED — y el error dice cuál falta, no un genérico:
```
{ "error": { "code": "SCOPE_REQUIRED", "details": { "scope": "expenses.read" } } }
```
Tu plan. Marcar expenses.read no sirve si tu plan no incluye el módulo de egresos. En el panel esos permisos salen en gris con candado. Y si bajas de plan, tus llaves no se revocan: se acotan. Si vuelves a subir, tu integración revive sola.
Los negocios de la llave. Una llave nunca ve un negocio que no esté en su lista, aunque se sepa el id. Pedir uno ajeno responde exactamente lo mismo que pedir uno inexistente.

Catálogo de permisos

Recurso	Permisos
Ingresos	`incomes.read` · `incomes.write` · `incomes.delete`
Verificación	`verifications.write`
Egresos	`expenses.read` · `expenses.write` · `expenses.delete`
Categorías	`categories.read` · `categories.write`
Pagos sospechosos	`suspicious.read` · `suspicious.resolve`
Negocio	`companies.read` · `branches.read` · `branches.write` · `payment_accounts.read` · `connections.read`
Equipo	`team.read` · `team.write`
Reportes	`metrics.read` · `plan.read`
Webhooks	`webhooks.read` · `webhooks.write`

Pide lo mínimo

Una llave de solo lectura que se filtre es un susto; una con incomes.delete es un incidente. Si tu integración solo consulta, no marques nada de escritura — siempre puedes ampliar los permisos de la llave después, sin cambiar el secreto.

Dónde se administran

Todo esto vive en el panel del negocio: Integraciones → API pública y webhooks → Llaves. Hace falta el permiso «Gestionar integraciones» (integration.manage), que por defecto tienen el Dueño y el Administrador.

Desde ahí se crean, se editan, se rotan y se revocan; y la tabla muestra el prefijo, el alias, el resumen de permisos, quién la creó y cuándo y desde qué IP se usó por última vez — que es lo que permite darse cuenta de una llave que nadie usa hace tres meses, o de una que se está usando desde un sitio raro.

No se pueden crear llaves desde la API

/v1 no expone ningún endpoint para acuñar, rotar o revocar llaves, y es a propósito: una llave que pudiera emitir llaves convertiría la fuga de una de solo lectura en una fuga total —bastaría usarla para emitir otra con todos los permisos—. Eso exige una sesión de una persona con permiso, y queda con su nombre encima.

Rotar una llave

Rotar genera un secreto nuevo sin dejarte abajo: la llave vieja sigue funcionando durante un periodo de gracia que tú eliges (por defecto 24 horas), el tiempo de desplegar.

llave vieja  ──────────── 24 h ────────────┤ deja de funcionar
llave nueva  ├──────────────────────────────────────────────────▶

Rota cuando: se te fue alguien del equipo que la tenía, la llave lleva más de un año viva, o por higiene periódica.

Si se te filtró

Rota con gracia cero. La vieja muere en el acto. Es preferible que tu integración se caiga diez minutos a que alguien más escriba en el libro del negocio.

Después revisa la columna último uso de la llave en el panel: te dice desde qué IP se usó por última vez.

Endurecerla más

Lista de IPs permitidas. Si tu integración corre en un servidor fijo, deja solo esa IP o su rango (190.85.0.0/16). Una llave robada deja de servir fuera de ahí.
Fecha de vencimiento. Para una integración temporal —una migración, una consultoría— ponle fecha desde el principio en lugar de confiar en que alguien se acuerde de borrarla.
Una llave por sistema. No compartas la misma entre tu ERP y tu bot: cuando toque revocar una, no quieres tumbar los dos.
Nunca en el navegador. La llave es de servidor. Si va en el frontend, cualquiera la lee en la pestaña de red.