Autenticación y claves
Cada petición a /v1 lleva una clave de API en la cabecera Authorization:
GET /v1/cuenta HTTP/1.1
Host: api.vintu.io
Authorization: Bearer vk_live_…La única excepción es la descarga de archivos: la URL de archivo_url ya lleva su propia credencial y no admite la
cabecera. Ver Descarga de archivos.
Formato
Una clave tiene la forma vk_live_<prefijo>_<secreto>:
vk_live_es fijo. No hay claves de prueba ni entorno de pruebas: toda clave lee los datos reales de tu cuenta.- El prefijo son 8 caracteres en minúsculas y dígitos. Es la parte visible que la app muestra en la lista de claves para que las distingas; por sí solo no autentica.
- El secreto son 32 caracteres (letras, dígitos,
-y_).
Una cabecera ausente, con otro esquema que no sea Bearer o con una clave que no tenga esa forma responde
401 INVALID_API_KEY, igual que una clave inexistente o revocada.
Crear una clave
Pueden crear y revocar claves el propietario de la cuenta y los administradores con acceso a todas las empresas, en
app.vintu.io, Configuración → API y webhooks:
- Crear clave, con un nombre que diga dónde se usa.
- Elige los permisos. Vienen marcados todos los de lectura; deja solo los que la integración necesite.
- Copia la clave. Se muestra una sola vez: Vintu guarda solo una huella (SHA-256) y no puede volver a enseñarla.
Toda clave de esta versión ve todas las empresas de la cuenta. El número de claves activas que admite tu cuenta
está en limites.max_api_keys de GET /v1/cuenta; las revocadas no cuentan.
Plan y acceso
La API está incluida en los planes Contador y Estudio. Cada petición comprueba el estado actual de la cuenta, no el que tenía al crear la clave:
| Situación | Respuesta |
|---|---|
| El plan no incluye la API (por ejemplo, Gratis) | 403 API_PLAN_REQUIRED |
| La cuenta no tiene acceso activo | 403 ACCESS_DENIED |
| La clave no tiene el permiso de la operación | 403 SCOPE_REQUIRED |
| Clave revocada, inexistente o mal formada | 401 INVALID_API_KEY |
Rotar una clave
No hay una operación de rotación. Para cambiar una clave sin cortar el servicio:
- Crea una clave nueva con los mismos permisos.
- Despliega la nueva en tu integración y comprueba que responde con
GET /v1/cuenta. - Revoca la anterior.
Mientras las dos estén activas, ocupan dos puestos de limites.max_api_keys.
Revocar una clave
En Configuración → API y webhooks, Revocar junto a la clave. La revocación deja de aceptar la clave en un máximo de 60 segundos, también en los enlaces de archivo que ya hubiera obtenido. No se puede deshacer: si hace falta, se crea otra.
Si una clave queda expuesta
Revócala primero y crea otra después. Una clave expuesta permite leer todos los datos de la cuenta que sus permisos alcanzan.
Buenas prácticas
- Guarda la clave en una variable de entorno o en un gestor de secretos, nunca en el código ni en un repositorio.
- Llama a la API desde tu servidor. No envía cabeceras CORS, y una clave en código de navegador queda a la vista de cualquiera.
- Usa una clave por integración, con los permisos justos: así puedes revocar una sin tocar las demás.
- No registres en tus logs la cabecera
Authorizationni las URL dearchivo_url.