Tokens API

• ¿Qué es un token API?
• Requisitos
• ¿Dónde encuentro los tokens API?
• Crear un token
• El token solo se muestra una vez
• Qué muestra la lista de tokens
• Revocar un token
• Usar el token

¿Qué es un token API?

Con la API REST de Klubraum, tus propios scripts, la web de tu club u otras herramientas pueden trabajar con los eventos del calendario y con los miembros de tu club. Cada solicitud se identifica con un token de acceso personal que creas en la app de Klubraum.

Un token de este tipo pertenece siempre a un único Klubraum y a la persona que lo ha creado. Solo tiene los alcances que tú le das, puede caducar y puedes revocarlo en cualquier momento. Y, sobre todo, un token nunca puede hacer más que tú: en cada solicitud se comprueban además tus permisos actuales en la app. Si pierdes un permiso, el token también lo pierde.

Requisitos

• Eres administrador del Klubraum. El resto de los miembros no ven esta función.
• Tu club tiene un plan adecuado: la lista de socios, las invitaciones y la eliminación de socios están incluidas en Plus, y cualquier otro endpoint requiere Pro. Sin un plan adecuado, al tocar el mosaico aparece un aviso para mejorar el plan.

¿Dónde encuentro los tokens API?

Abre los Ajustes y ve a Klubraum actual. El segundo mosaico se llama Tokens API, con el subtítulo Tokens de acceso personal para la API de Klubraum, justo debajo del mosaico para cambiar el nombre del club.

Atención: el mosaico que aparece justo debajo corresponde al token de las solicitudes de adhesión. Ese es un token diferente, pensado solo para el formulario de adhesión de la web de tu club; puedes leer más en Solicitud de adhesión en la web del club.

Crear un token

Toca el + de la parte superior derecha (Crear token). El cuadro de diálogo Crear token API te pide tres cosas.

Nombre

Texto libre de un máximo de 100 caracteres, por ejemplo “Sincronización de la web”. Dale a cada herramienta su propio token y ponle el nombre de esa herramienta: así sabrás más adelante exactamente qué token puedes revocar.

Alcances

Aquí decides qué puede hacer el token. Hay cuatro alcances:

• members:read – leer la lista de miembros.
• members:write – invitar y eliminar miembros.
• events:read – leer los eventos del calendario.
• events:write – crear, modificar, cancelar y eliminar eventos del calendario.

Un alcance de escritura siempre incluye el alcance de lectura correspondiente. En cuanto marcas members:write, members:read se marca automáticamente y ya no se puede desmarcar; en el token solo se guarda entonces el alcance de escritura. Lo mismo ocurre con events:write y events:read. Se requiere al menos un alcance.

Consejo: elige los menos alcances posibles. A un script que solo muestra vuestros eventos en vuestra web le basta con events:read.

Caduca después de

Elige 30, 90, 180 o 365 días, o bien Nunca. Con Nunca aparece una advertencia, y con razón: un token sin fecha de caducidad sigue siendo válido hasta que alguien lo revoca. Por eso, siempre que puedas, dale al token una vida útil limitada.

Después toca Crear.

El token solo se muestra una vez

Justo después de crearlo, la app te muestra el token completo: la larga cadena secreta que empieza por klubraum_pat_. Cópiala con el botón de copiar y guárdala enseguida allí donde la lee tu script o herramienta, preferiblemente en un gestor de contraseñas o en un almacén de secretos.

Importante: este es el único momento en el que la cadena secreta es visible. Después ya no se puede recuperar, ni siquiera por nuestra parte. Si la pierdes, revoca el token y crea uno nuevo.

Nunca pongas la cadena secreta en un lugar público: ni en el JavaScript de vuestra web, ni en un repositorio público, ni en una conversación del club. Quien la tenga puede usar la API exactamente con los alcances que le hayas dado al token.

Qué muestra la lista de tokens

En la pantalla ves todos los tokens de tu Klubraum. De cada uno encuentras:

• el nombre que le has puesto,
• un prefijo corto que empieza por klubraum_pat_ y que identifica el token sin revelar la cadena secreta,
• los alcances en forma de chips,
• cuándo se creó, cuándo caduca y cuándo se usó por última vez.

Por la fecha del último uso reconocerás fácilmente los tokens que ya no necesita nadie. Los tokens revocados permanecen en la lista y se muestran tachados.

Revocar un token

Toca el icono de eliminar del token correspondiente (Revocar token) y confirma con Sí, revocar. La revocación tiene efecto de inmediato: a partir de ese momento se rechaza cualquier solicitud realizada con ese token. No se puede deshacer: un token revocado no se puede volver a activar.

Consejo: ¿quieres sustituir un token que todavía está en uso? Entonces crea primero el token nuevo, cambia tu script o herramienta a ese token y revoca el antiguo solo después.

Usar el token

Envía el token en cada solicitud como bearer token en la cabecera Authorization:

Authorization: Bearer klubraum_pat_…

Qué endpoints existen, qué parámetros esperan y qué devuelven se describe en la sección para desarrolladores y en la referencia de la API interactiva. En inglés.