How to use refresh tokens es

Los tokens de actualización permiten renovar el acceso sin volver a enviar las credenciales del usuario. Son opcionales y deben estar habilitados en la aplicación que autentica el inicio de sesión.

Ver también: English version

Habilitar tokens de actualización

En el backoffice de Betterez vaya a Administración → Integraciones → Aplicaciones, abra su aplicación y active Use refresh tokens. Configure la duración del token de acceso y del token de actualización según necesite.

Si la opción está desactivada, los tokens de acceso duran 2 días y las respuestas de login no incluyen refreshToken.

Cuándo se devuelve un token de actualización

Si los tokens de actualización están habilitados para la aplicación, las respuestas de login pueden incluir el campo refreshToken:

Endpoint de login Uso típico
POST /accounts/users Usuarios del backoffice
POST /accounts/customers Login de clientes
POST /accounts/applications Autenticación de aplicaciones

Use shortToken como JWT Bearer en las peticiones a la API, como se describe en How to use your JSON Web Token.

Guarde el refreshToken de forma segura en su servidor. Evite exponerlo en código del lado del cliente cuando sea posible.

Canjear un token de actualización

Llame a POST /accounts/refresh-token cuando el token de acceso esté por vencer o tras recibir 401 en una petición autenticada.

Solo se requiere la clave pública de la aplicación en el encabezado X-API-KEY. No se usa Basic Auth en esta petición.

curl --request POST \
  --url https://api.betterez.com/accounts/refresh-token \
  --header 'content-type: application/json' \
  --header 'x-api-key: {{x-api-key}}' \
  --data '{"refreshToken": "{{refresh-token}}"}'

Si la operación es exitosa, la respuesta tiene la misma forma que el endpoint de login que emitió el token (usuario, cliente o aplicación) e incluye un nuevo shortToken. Si los tokens de actualización siguen habilitados, también se devuelve un nuevo refreshToken.

Cada token de actualización es de un solo uso. Tras un canje exitoso, descarte el token anterior y guarde el nuevo.

Errores

HTTP Código Significado
400 WRONG_DATA Falta refreshToken en el cuerpo
401 (encabezado) X-API-KEY ausente o inválido
401 INVALID_REFRESH_TOKEN Token inválido, vencido, ya usado o el sujeto ya no puede iniciar sesión

Si el canje falla, autentíquese de nuevo con el endpoint de login original.

Postman

Colección Postman

Entorno Postman

Importe ambos archivos, configure x-api-key, basicAuthToken y audience en el entorno y ejecute las peticiones en orden.