Autenticación: claves, permisos y ámbito
Cómo se crea una clave de API, qué permisos puede llevar, a qué salas alcanza y por qué nunca debe salir de tu servidor.
Última actualización: 23 de agosto de 2026
Todas las llamadas a /api/v1 van autenticadas con una clave de API. No hay endpoints públicos ni anónimos.
Cómo se manda la clave
Authorization: Bearer tk_live_a1B2c3D4e5F6_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYYYYYY
También se acepta la cabecera X-Api-Key con el mismo valor, porque hay plataformas de automatización que no dejan fijar Authorization a mano:
X-Api-Key: tk_live_a1B2c3D4e5F6_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYYYYYY
Las dos son equivalentes. Si mandas las dos, gana Authorization.
La regla que no se puede saltar
No la pongas en una web, en una app móvil, en un widget ni en ningún cliente que el usuario final pueda inspeccionar. Cualquiera que abra las herramientas de desarrollo del navegador o descomprima tu app la leerá en diez segundos, y con ella podrá hacer todo lo que la clave permita.
Para que no ocurra por accidente, Tickeep no habilita CORS en /api/v1. Una llamada desde el navegador falla siempre, y falla a propósito. No es un fallo de configuración ni algo que podamos activarte: es el mecanismo que impide que una clave acabe en un bundle de JavaScript.
Si necesitas vender o mostrar datos en tu web, la llamada la hace tu backend y tu frontend habla con tu backend. En vender desde tu web está el circuito completo.
Cómo reconocer una clave
Toda clave empieza por tk_live_ o tk_test_, así que de un vistazo sabes con qué entorno estás hablando. Después del prefijo viene un identificador público, y a continuación el secreto.
Ese identificador público es la parte que el panel te enseña para distinguir unas claves de otras. Puedes escribirlo en tus logs sin ningún riesgo, y es lo que te pediremos si abres un ticket. El resto de la clave no debe salir nunca de tus variables de entorno.
Las claves llevan una comprobación interna que detecta una copia incompleta —un salto de línea de más, un espacio al final, un carácter que se quedó fuera— antes incluso de consultarla. Si recibes invalid_credentials nada más empezar, casi siempre es eso y no que la clave esté mal emitida.
Dónde se crea
En el panel, en Configuración → Desarrolladores. Necesitas el rol de propietario o administrador de la organización: quien puede tocar la facturación puede emitir credenciales, y nadie más.
Al crear la clave verás el valor completo. Después no vuelve a estar disponible: Tickeep no la guarda en claro en ningún sitio, así que ni el equipo de soporte puede recuperártela. Si la pierdes, se emite otra y se revoca la vieja.
Guárdalo donde guardes el resto de tus secretos —variables de entorno, un gestor de secretos, lo que uses—. Nunca en el código.
Permisos
Cada clave se emite con una lista de permisos. Marcas solo los que la integración necesita.
| Permiso | Qué te deja hacer |
|---|---|
catalog:read | Leer salas, eventos, fechas, tipos de entrada y disponibilidad. Sin datos personales. |
orders:read | Consultar pedidos, con los datos del comprador. |
orders:write | Reservar, confirmar y cancelar ventas. |
tickets:read | Consultar entradas emitidas. |
tickets:validate | Marcar entradas como usadas en el control de acceso. |
customers:read | Listado de asistentes con sus datos de contacto. |
reports:read | Recaudación y estadísticas. |
Permisos que incluyen otros
Dos de ellos arrastran lo que necesitan para ser útiles, así que no hace falta que marques los dos:
orders:writeincluyeorders:readycatalog:read. Poder crear un pedido y no poder leerlo después no sirve de nada.tickets:validateincluyetickets:read.
El techo
Ya está dicho en la introducción, pero conviene repetirlo aquí: ninguna combinación de permisos concede administración. Una clave con los siete permisos marcados sigue sin poder crear un evento, invitar a nadie, cambiar precios en el catálogo ni emitir un reembolso.
Ámbito de salas
Además de los permisos, una clave se emite para todas las salas de tu organización o para una lista concreta.
Esto acota absolutamente todo, no solo lo que pides explícitamente:
- Un listado sin filtros devuelve únicamente lo que la clave alcanza.
- Pedir un recurso de una sala fuera de su ámbito responde
404 not_found, no403 forbidden.
Que responda 404 y no 403 es intencionado. Si distinguiéramos «no existe» de «existe pero no puedes», la API se convertiría en un detector de identificadores ajenos: bastaría con probar ids y mirar el código de respuesta para saber cuáles son reales.
Es lo que hace segura la integración de una sala con su proveedor de control de acceso: le das una clave acotada a esa sala, y ese proveedor no puede ni ver que existen las demás.
Rotar una clave
Puedes tener dos claves activas a la vez, que es lo que hace posible rotar sin cortar el servicio:
Emite la clave nueva
Con los mismos permisos y el mismo ámbito que la vieja.
Despliégala
Cambia la variable de entorno en tu servidor y comprueba que el tráfico entra con la nueva. En el panel verás la marca de último uso de cada una.
Caduca la vieja
Ponle fecha de caducidad para dar margen a un despliegue a medias, o revócala directamente si estás seguro.
Revocar es inmediato. Si sospechas que una clave se ha filtrado, revócala y emite otra: no esperes a la ventana de mantenimiento.
Entorno de pruebas
Existen claves tk_test_ y se distinguen de las tk_live_ por el prefijo.
Hoy tk_test_ sirve para separar credenciales y tráfico, no para aislar los datos. Un pedido creado con una clave de pruebas es un pedido de verdad en tu organización.
Mientras no haya un sandbox completo, lo que recomendamos es crear una sala de pruebas en tu organización y acotar la clave de test a esa sala. Así lo que hagas mientras integras no se mezcla con la recaudación de la sala real, y los informes siguen cuadrando.
Errores de autenticación
| Código | HTTP | Qué ha pasado |
|---|---|---|
not_authenticated | 401 | No has mandado ninguna credencial |
invalid_credentials | 401 | La clave está mal escrita, revocada o caducada |
forbidden | 403 | La clave es válida pero le falta el permiso |
not_found | 404 | El recurso no existe o está fuera del ámbito de salas de la clave |
No distinguimos entre «mal escrita» y «no existe» en el 401 a propósito: es información que solo le sirve a quien está probando claves.
Seguir por aquí
Acceso programático a tu catálogo, tus ventas y tus entradas. Qué puedes construir, qué no concede nunca una clave y cómo está organizada esta referencia.
Cinco llamadas que van de crear una clave a emitir una entrada de verdad, con el porqué de cada paso.
Todos los códigos que devuelve la API, qué significa cada uno y cuáles tiene sentido reintentar.