Saltar al contenido
Vintu API
Tema de la documentación
Ir a la app

Autenticación y claves

Cada petición a /v1 lleva una clave de API en la cabecera Authorization:

HTTP
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:

  1. Crear clave, con un nombre que diga dónde se usa.
  2. Elige los permisos. Vienen marcados todos los de lectura; deja solo los que la integración necesite.
  3. 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ónRespuesta
El plan no incluye la API (por ejemplo, Gratis)403 API_PLAN_REQUIRED
La cuenta no tiene acceso activo403 ACCESS_DENIED
La clave no tiene el permiso de la operación403 SCOPE_REQUIRED
Clave revocada, inexistente o mal formada401 INVALID_API_KEY

Rotar una clave

No hay una operación de rotación. Para cambiar una clave sin cortar el servicio:

  1. Crea una clave nueva con los mismos permisos.
  2. Despliega la nueva en tu integración y comprueba que responde con GET /v1/cuenta.
  3. 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 Authorization ni las URL de archivo_url.