Autenticación

Todas las llamadas viajan con una API key en la cabecera Authorization:

curl https://api.ventry.es/v1/event \
  -H "Authorization: Bearer vk_live_8Kq2ZxR7pN3mW9tYbC4vD6fH1jL5sA0e"

await fetch("https://api.ventry.es/v1/event", {
  headers: { Authorization: `Bearer ${process.env.VENTRY_KEY}` },
});

requests.get(
    "https://api.ventry.es/v1/event",
    headers={"Authorization": f"Bearer {os.environ['VENTRY_KEY']}"},
    timeout=10,
)

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("VENTRY_KEY"),
]);

Obtener una clave

La emite el organizador del evento desde el panel de VENTRY, en API / Integraciones. Al crearla elige:

Permisos (scopes): qué puedes leer y escribir.
Ámbito: si la clave se limita a ciertos tipos de entrada o días.
Límite de peticiones por minuto.
IPs autorizadas, si quiere restringir desde dónde se puede usar.

La clave se muestra una sola vez, en el momento de crearla. VENTRY sólo guarda un hash, así que ni el organizador ni el equipo de VENTRY pueden recuperarla después. Si se pierde, hay que revocarla y emitir otra.

Claves con permisos de escritura

Cualquier clave que pida un permiso de escritura nace desactivada y responde:

{
  "error": {
    "type": "permission_error",
    "code": "key_pending_activation",
    "message": "Esta API key solicita permisos de escritura y todavía no ha sido activada por un administrador del evento.",
    "request_id": "req_9f2c1a4e7b304d51"
  }
}

Es intencionado: escribir en un evento en marcha —crear entradas, acreditar asistentes, mover saldo— exige que una persona lo autorice de forma explícita. Pídele al organizador que la active desde el panel.

Permisos

Scope	Qué permite	Activación
`event.read`	Días, zonas, tipos de entrada y datos del evento	Automática
`tickets.read`	Consultar entradas y su estado	Automática
`tickets.write`	Crear y anular entradas	Manual
`checkins.read`	Registro de escaneos en puerta	Automática
`checkins.write`	Acreditar entradas y validar zonas	Manual
`cashless.read`	Saldos, consumiciones y recargas	Automática
`cashless.write`	Recargar saldo de pulseras	Manual
`reports.read`	Resumen agregado de ventas	Automática
`*`	Todo, presente y futuro	Manual

Llamar a un endpoint sin su permiso devuelve 403 insufficient_scope.

Formato de la clave

vk_live_8Kq2ZxR7pN3mW9tYbC4vD6fH1jL5sA0e
└┬┘ └┬─┘ └──────────────┬──────────────┘
 │   │                  └─ secreto (32 bytes aleatorios)
 │   └──────────────────── entorno: live o test
 └──────────────────────── prefijo de VENTRY

El prefijo vk_live_ no es decorativo: permite que los escáneres de secretos de GitHub y similares detecten una clave publicada por error.

Buenas prácticas

Guárdala como un secreto de servidor

Una API key de VENTRY puede leer datos personales de asistentes y, según sus permisos, escribir en el evento. Nunca la incrustes en una aplicación móvil, en JavaScript de navegador ni en un repositorio. Si tu aplicación de puerta necesita acreditar, que hable con tu backend y sea éste quien llame a VENTRY.

Pide sólo los permisos que uses

Si únicamente vuelcas entradas, pide event.read y tickets.write. Cuantos menos permisos, menos daño hace una clave comprometida.

Usa el ámbito

Si sólo gestionas un tipo de entrada, pídele al organizador que limite la clave a ese tipo. Deja de ser posible tocar por error entradas que no son tuyas.

Rota sin cortes

No hay rotación automática. Para rotar sin interrumpir el servicio: pide una clave nueva, despliégala, comprueba que funciona con GET /ping, y sólo entonces pide que revoquen la anterior. Una clave revocada deja de funcionar de inmediato.

Registra el request_id

Cada respuesta lleva la cabecera X-Request-Id. Guárdala en tus logs: es lo que permite al soporte de VENTRY encontrar tu petición exacta.

Errores de autenticación

Código	Situación
`missing_api_key`	Falta la cabecera `Authorization` o no tiene el formato `Bearer vk_...`
`invalid_api_key`	La clave no existe
`revoked_api_key`	La clave fue revocada
`expired_api_key`	La clave tenía fecha de caducidad y ya pasó
`key_pending_activation`	Tiene permisos de escritura sin activar
`ip_not_allowed`	Tu IP no está en la lista autorizada de la clave
`insufficient_scope`	La clave no tiene el permiso que exige ese endpoint

Empezar

Fundamentos

Casos de uso

Próximamente

Obtener una clave

Claves con permisos de escritura

Permisos

Formato de la clave

Buenas prácticas

Errores de autenticación

​Obtener una clave

​Claves con permisos de escritura

​Permisos

​Formato de la clave

​Buenas prácticas

​Errores de autenticación

Obtener una clave

Claves con permisos de escritura

Permisos

Formato de la clave

Buenas prácticas

Errores de autenticación