## 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](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/) `(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](#como-anadir-otro-token) 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. > [!CAUTION] > No comparta nunca el token ni lo suba a un repositorio público. Cualquiera que > tenga el token y el Application ID puede enviar mensajes desde su cuenta. Si > sospecha que se ha filtrado, [regenere](#como-regenerar-un-token) o > [elimine](#como-eliminar-un-token) el token. ## 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`. ![La parte Credenciales de acceso con la lista de tokens](docs:api-tokens/token-list_en) ## 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 ![El diálogo Mostrar ficha que solicita la contraseña](docs:api-tokens/token-show_en) > [!NOTE] > Un token mostrado permanece visible solo hasta que se recarga la página. Tras > recargarla vuelve a ocultarse y tendrá que introducir de nuevo su contraseña para verlo. ## 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 menú Mas acciones con Generar uno nuevo, Inhabilitar y Borrar](docs:api-tokens/token-menu_en) El portal lo confirma con `El token ha sido regenerado.` > [!WARNING] > El token anterior deja de funcionar de inmediato. Todas las integraciones que lo > utilizaban empiezan a recibir errores: sustitúyalo por el nuevo token sin demora. ## 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. > [!CAUTION] > La eliminación es definitiva: el token no se puede restaurar ni volver a mostrar. Si > solo quiere bloquear el acceso temporalmente, utilice en su lugar > [la desactivación del token](#como-desactivar-y-volver-a-activar-un-token). 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](#como-usar-el-token-en-un-jwt-firmado) 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](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/). ## 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`: ```http POST /api/1.0/simple/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json Authorization: Bearer ``` Para que la API lo acepte, el JWT debe tener este aspecto: | Parte | Contenido | |:--|:--| | Header | `{"alg":"HS256","typ":"JWT"}` — la API no acepta ningún otro algoritmo ni tipo | | Payload | `application_id` con su [Application ID](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/) | | Signature | HMAC-SHA256 del header y el payload, con el token de API como clave | Así, el payload para la aplicación número 39238 tiene este aspecto: ```json { "application_id": 39238 } ``` > [!NOTE] > Cuando envía un JWT, ya no necesita `application_id` ni `application_token` > entre los parámetros de la solicitud: la API toma la identidad del payload. 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: ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` 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`.