Refresh a JWT

This can be used to extend a centrally managed session when a refresh token represents a user session. Learn more about using refresh tokens to model sessions.

This endpoint does not accept a resource parameter. However, if the application's oauthConfiguration.authorizedResourceUris is non-empty and the refresh token carries resource URIs in its metaData.resources field (set during the original authorization code exchange), those resources are automatically applied to the newly issued access token. The aud claim of the new token will be an array ["client_id", "https://resource1.example.com", ...] when resources are present, or a plain UUID string when they are not.

Request#

Request a new Access Token by presenting a valid Refresh Token.

POST/api/jwt/refresh

OpenAPI Spec

The refresh token may be provided either in the HTTP request body or as a cookie. If both are provided, the cookie will take precedence.

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Cookies#

refresh_tokenStringoptional

The refresh token to be used to obtain a new access token.

This value is required but optional as a cookie. It must be provided in either the request body or as a cookie.

access_tokenStringoptional

The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the original field.

Request Body#

refreshTokenStringoptional

The refresh token to be used to obtain a new access token.

This value is required but optional in the request body. It must be provided in either the request body or as a cookie.

tokenStringoptional

The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the original field.

timeToLiveInSecondsIntegeroptionalAvailable since 1.59.0

The time to live for the new access token.

When provided on the request, this value will override the default TTL, provided it is less than the default value. The default TTL is taken from application.jwtConfiguration.timeToLiveInSeconds if it is set there, otherwise it is taken from tenant.jwtConfiguration.timeToLiveInSeconds.

Example Request JSON

{
  "refreshToken": "xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFuYV91STRWbWxiMU5YVXZ0cV83SjZKZFNtTSJ9.eyJleHAiOjE1ODgzNTM0NjAsImlhdCI6MTU4ODM1MzQwMCwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.ZoIHTo3Pv0DpcELeX_wu-ZB_rd988jefZc2Ozu9_p59kttwqMm5PV8IDbgxJw9xcq9TFoNG8e_B6renoc11JC54UbiyeXBjF7EH01n9LDz-zTGqu9U72470Z4E7IPAHcyvJIBx4Mp9sgsEYAUm9Tb8ChudqNHhn6ZnXYI7Sew7CtGlu62f10wdBYGX0soYARHBv9CwhJC3-gsD2HLmqHAP_XhrpaYPNr5EAvmCHlM-JlTiEQ9bXwSc4gv-XbPQWamwy8Kcdb-g0EEAml_dC_b2CduwwYg0EoPQB3tQxzTUQzADi7K6q0CtQXv2_1VrRi6aQ4lt7v7t-Na39wGry_pA"
}

Example POST HTTP Request containing Cookie Header

POST /api/jwt/refresh HTTP/1.1
Cookie: refresh_token=xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc; access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFuYV91STRWbWxiMU5YVXZ0cV83SjZKZFNtTSJ9.eyJleHAiOjE1ODgzNTM0NjAsImlhdCI6MTU4ODM1MzQwMCwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.ZoIHTo3Pv0DpcELeX_wu-ZB_rd988jefZc2Ozu9_p59kttwqMm5PV8IDbgxJw9xcq9TFoNG8e_B6renoc11JC54UbiyeXBjF7EH01n9LDz-zTGqu9U72470Z4E7IPAHcyvJIBx4Mp9sgsEYAUm9Tb8ChudqNHhn6ZnXYI7Sew7CtGlu62f10wdBYGX0soYARHBv9CwhJC3-gsD2HLmqHAP_XhrpaYPNr5EAvmCHlM-JlTiEQ9bXwSc4gv-XbPQWamwy8Kcdb-g0EEAml_dC_b2CduwwYg0EoPQB3tQxzTUQzADi7K6q0CtQXv2_1VrRi6aQ4lt7v7t-Na39wGry_pA

Response#

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	Either the timeToLiveInSeconds request field is greater than the allowed TTL, or the provided Refresh Token is either expired, was not found, or has been revoked.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

refreshTokenString

The refresh token.

When jwtConfiguration.refreshTokenUsagePolicy is equal to Reusable this will be equal to the refresh token provided in the request. When jwtConfiguration.refreshTokenUsagePolicy is equal to OneTimeUse a new value will be returned and the previous refresh token value will no longer be valid.

The jwtConfiguration.refreshTokenUsagePolicy is configured at the tenant, and optionally per application.

refreshTokenIdStringAvailable since 1.37.0

This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the Refresh Token API.

tokenString

The encoded access token.

Example Response JSON

{
  "refreshToken": "A0czpESaoeGxQdfanF3aFYzfo-AnsnKaqhjlHpzcROcRD91j7rgVBw",
  "refreshTokenId": "bc767324-52fc-48c0-8bf0-af1d11e17ac3",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODc5NzU0NTgsImlhdCI6MTQ4Nzk3MTg1OCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI4NThhNGIwMS02MmM4LTRjMmYtYmZhNy02ZDAxODgzM2JlYTciLCJhcHBsaWNhdGlvbklkIjoiM2MyMTllNTgtZWQwZS00YjE4LWFkNDgtZjRmOTI3OTNhZTMyIiwicm9sZXMiOlsiYWRtaW4iXX0.O29_m_NDa8Cj7kcpV7zw5BfFmVGsK1n3EolCj5u1M9hZ09EnkaOl5n68OLsIcpCrX0Ue58qsabag3MCNS6H4ldt6kMnH6k4bVg4TvIjoR8WE-yGcu_xDUObYKZYaHWiNeuDL1EuQQI_8HajQLND-c9juy5ILuz6Fhx8CLfHCziEHX_aQPt7jQ2IIasVzprKkgvWS07Hiv2Oskryx49wqCesl46b-30c6nfttHUDEQrVq9gaepca3Nhjj_cPtC400JgLCN9DOYIbtd69zvD8vDUOvVzMr2HGdWtKthqa35NF-3xMZKD8CShe8ZT74fNd9YZ0WRE-YeIf3T_Hv5p5V2w"
}

Response Cookies#

access_tokenString

The encoded access token. This cookie is written in the response as an HttpOnly session cookie.

refresh_tokenString

The encoded refresh token.

This cookie is written in the response as an HttpOnly cookie. When jwtConfiguration.refreshTokenUsagePolicy is equal to Reusable this will be equal to the refresh token provided in the request. When jwtConfiguration.refreshTokenUsagePolicy is equal to OneTimeUse a new value will be returned and the previous refresh token value will no longer be valid.

The jwtConfiguration.refreshTokenUsagePolicy is configured at the tenant, and optionally per application.