Tokens de API

Qué es un token de API

Un token de API (APPLICATION_TOKEN) es la clave secreta con la que su aplicación se autentica ante la API de BulkGate. Junto con el Application ID (APPLICATION_ID) forma el conjunto completo de credenciales de acceso: sin ambos, la API rechaza la solicitud.

El token es una cadena aleatoria de 50 caracteres compuesta por dígitos y letras minúsculas y mayúsculas. Se almacena cifrado y no caduca: sigue siendo válido hasta que usted mismo lo regenere, lo desactive o lo elimine.

Se crea un token automáticamente en el momento en que crea la API. Puede añadir más en cualquier momento, por ejemplo uno por servidor o por entorno, de modo que pueda revocar uno sin que afecte a los demás.

Dónde encontrar el token

1. Haga clic en Módulos y APIs en el menú del portal
2. Haga clic en la tarjeta de su aplicación en Mis APIs y módulos
3. Permanezca en la pestaña Ajustes y busque la sección Credenciales de acceso

Contiene el Application ID y, debajo, bajo el subtítulo Application Token, la lista de tokens de esa aplicación. El token nunca se muestra de inmediato: solo verá sus cuatro primeros y cuatro últimos caracteres, el resto se sustituye por asteriscos.

El icono de la izquierda indica el estado del token: verde significa activado, rojo significa desactivado. Un token desactivado aparece además tachado.

El botón con el ojo tachado a la derecha de cada token lo muestra; las demás acciones están ocultas tras el icono de tres puntos Mas acciones.

Cómo mostrar y copiar un token

1. Haga clic en el icono del ojo tachado junto al token que quiere ver
2. Se abre el diálogo Mostrar ficha, que le pide que compruebe su entorno
3. Introduzca la contraseña de su cuenta y haga clic en Continuar
4. El token se muestra completo y el icono cambia a Dupdo, que lo copia al portapapeles

Cómo añadir otro token

1. Haga clic en Añadir token en la parte inferior de la sección Credenciales de acceso
2. Introduzca la contraseña de su cuenta
3. Haga clic en Añadir

El portal lo confirma con Token ha sido creado y muestra el nuevo token completo: cópielo de inmediato, porque tras recargar la página se oculta como los demás. No hay límite en el número de tokens que puede tener una aplicación.

Cómo regenerar un token

Al regenerarlo, el token existente se sobrescribe con uno nuevo. Conserva su lugar en la lista, solo cambia su valor.

1. Haga clic en Mas acciones junto al token y elija Generar uno nuevo
2. Introduzca la contraseña de su cuenta
3. Haga clic en Generar uno nuevo

El portal lo confirma con El token ha sido regenerado.

Cómo desactivar y volver a activar un token

Desactivar un token es la alternativa reversible a eliminarlo: el token permanece en la lista, pero ya no puede utilizarse para autenticarse.

1. Haga clic en Mas acciones junto al token
2. Elija Inhabilitar, o Habilitar si el token ya está desactivado
3. Confirme en el diálogo que se abre

El portal lo confirma con El token ha sido deshabilitado. o El token fue habilitado. Esta acción no requiere contraseña.

Cómo eliminar un token

1. Haga clic en Mas acciones junto al token y elija Borrar
2. Confirme con Borrar en el diálogo Eliminar token

El portal lo confirma con Se ha eliminado el token. Esta acción tampoco requiere contraseña.

Todos los tokens de una aplicación desaparecen también en el momento en que elimina la propia aplicación.

Cómo se envía el token a la API

El Application ID y el token se pasan como parámetros application_id y application_token, ya sea en el cuerpo de la solicitud o en la query string. La otra opción es firmar un JWT con el token y enviarlo en una cabecera.

Un token no válido, desactivado o eliminado provoca una respuesta con el código HTTP 401 y el tipo de error unknown_identity. Obtendrá la misma respuesta cuando la propia aplicación esté desactivada, o cuando tenga configuradas direcciones IP permitidas y la solicitud proceda de otra dirección. Los demás errores se enumeran en la página Tipos de error de la API.

Cómo usar el token en un JWT firmado

En lugar de enviar el token con cada solicitud, puede firmar con él un JWT y enviar este en su lugar. El token se queda entonces de su lado: por la red solo viaja la firma derivada de él.

Coloque el JWT terminado en la cabecera Authorization:

Para que la API lo acepte, el JWT debe tener este aspecto:

Así, el payload para la aplicación número 39238 tiene este aspecto:

Puede limitar la validez de un JWT concreto con el campo expire dentro de application_parameters. El valor es una marca de tiempo Unix en segundos; una vez alcanzada, el JWT deja de funcionar:

Sin este campo, el JWT es válido mientras lo sea el token que lo firmó. Por eso resulta útil allí donde entregue el JWT a terceros: lo firma con una validez corta y el token en sí se queda con usted.

La firma se verifica frente a todos los tokens activados de la aplicación, así que puede firmar el JWT con cualquiera de ellos. Un token desactivado o eliminado no pasa: se aplica lo mismo que se ha descrito antes, una respuesta con el código HTTP 401 y el tipo de error unknown_identity.