Skip to content

Refresh token

Refresh Tokens

The refresh token provides a way to refresh the JWT token used as a authorization bearer.

The refresh token is a str generated using uuid4 and stored in the database as user.refresh_token

Validity

The refresh token is a long lived token, it is regenerated each login, with a new expiration date.

The expiration date is a datetime stored in the database as user.refresh_token_expiration_date

Modify refresh token validity

The variable used for the refresh token validity is TOUCAN_REFRESH_TOKEN_VALIDITY

Its default value is 30 days

The default value for the JWT token validity is also 30 days

Usage

The refresh token is sent in the response when logging in (/login): 

$ curl 'http://0.0.0.0:5000/login' \
-H 'content-type: application/json'  \ 
--data-binary $'{"username":"username","password":"password"}' 
{
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
   "refresh_token": "ab91d18b-242a-4daf-9fd1-09f4fb803f48", 
   "user_uid": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

You can then refresh the token (/refresh):

$ curl 'http://0.0.0.0:5000/refresh' \ 
-H 'content-type: application/json'  \
-H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' \
--data-binary $'{"refresh_token":"ab91d18b-242a-4daf-9fd1-09f4fb803f48"}' 
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", # new token (new expiration date)
"refresh_token": "ab91d18b-242a-4daf-9fd1-09f4fb803f48" # same token
}

Refresh token errors

If an error occurs during the refreshing of a JWT token while validating the refresh token, a 401 Unauthorized error is returned with an explicit message of the error.

Error messages:

  • Invalid refresh token
  • Expired refresh token