/Docs

Retrieve Refresh Tokens

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

Request#

API Key Authentication
Retrieve a Single Refresh Token
GET/api/jwt/refresh/{tokenId}
OpenAPI Spec

Request Parameters#

tokenIdUUIDrequired

The Id of the token.

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.

Response#

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404The refresh token specified by the tokenId is missing or revoked.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

refreshToken.applicationIdString

The Id of the Application for which this token is authorized to be exchanged for a new Access Token. If this Id is not present, the token cannot be used to obtain an access token for an Application.

refreshToken.insertInstantLong

The instant this Refresh Token was issued.

refreshToken.idUUID

The Id of the Refresh Token.

refreshToken.metaData.device.descriptionString

A description of the device. For example, Hooli Phone 8GB Work Phone.

refreshToken.metaData.device.lastAccessedAddressString

The IP address of the device when this Refresh Token was last used.

refreshToken.metaData.device.lastAccessedInstantLong

The instant this Refresh Token was last used.

refreshToken.metaData.device.nameString

The name of the device, for example Richard's Hooli Phone.

refreshToken.metaData.device.typeString

The type of device represented by the device parameter.

Prior to version 1.46.0, this value was restricted to the following types:

  • BROWSER
  • DESKTOP
  • LAPTOP
  • MOBILE
  • OTHER
  • SERVER
  • TABLET
  • TV
  • UNKNOWN

In version 1.46.0 and beyond, this value can be any string value you'd like, have fun with it!

refreshToken.metaData.resourcesArray<String>Available since 1.67.0

The resource URIs associated with this Refresh Token, per RFC 8707 (Resource Indicators for OAuth 2.0). This field is populated during the authorization code exchange when a resource parameter was provided and validated against the application's oauthConfiguration.authorizedResourceUris.

These values are used as the reference point for resource validation in subsequent refresh token grants and /api/jwt/refresh calls.

refreshToken.metaData.scopesArray<String>

The scopes associated with this Refresh Token. These are set at authentication when the Refresh Token is first created.

refreshToken.startInstantLong

The instant of the start of this Refresh Token. This value will be used to calculate token expiration.

refreshToken.tokenString

The string representation of the encoded Refresh Token. This value should be kept in some sort of secure storage and treated as sensitive information.

refreshToken.userIdUUID

The User Id of the user for which this Refresh Token was issued.

Example Response JSON For a Single Refresh Token

{
  "refreshToken": {
    "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
    "insertInstant": 1487971807175,
    "id": "ae19cbd9-a6d5-496c-b195-0ab7069dbd1d",
    "metaData": {
      "device": {
        "description": "Hooli Phone 8GB Work Phone",
        "lastAccessedAddress": "170.152.81.62",
        "lastAccessedInstant": 1487996477628,
        "name": "Richard's Hooli Phone",
        "type": "MOBILE"
      },
      "scopes": [
        "offline_access"
      ]
    },
    "startInstant": 1487971808178,
    "token": "xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc",
    "userId": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
  }
}
API Key Authentication
Retrieve Refresh Tokens issued to a User
GET/api/jwt/refresh?userId={userId}
OpenAPI Spec

Request Parameters#

userIdUUIDrequired

The Id of the user for whom to retrieve issued Refresh Tokens.

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.

Response#

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Only 1,000 tokens, in descending order of creation, will be returned. If more than 1,000 refresh tokens have been issued to the user, the oldest refresh tokens will be omitted.

Response Body#

refreshTokensArray

An array of Refresh Tokens

refreshToken[x].applicationIdString

The Id of the Application for which this token is authorized to be exchanged for a new Access Token. If this Id is not present, the token cannot be used to obtain an access token for an Application.

refreshToken[x].insertInstantLong

The instant this Refresh Token was issued.

refreshToken[x].idUUID

The Id of the Refresh Token.

refreshToken[x].metaData.device.descriptionString

A description of the device. For example, Hooli Phone 8GB Work Phone.

refreshToken[x].metaData.device.lastAccessedAddressString

The IP address of the device when this Refresh Token was last used.

refreshToken[x].metaData.device.lastAccessedInstantLong

The instant this Refresh Token was last used.

refreshToken[x].metaData.device.nameString

The name of the device, for example Richard's Hooli Phone.

refreshToken[x].metaData.device.typeString

The type of device represented by the device parameter.

Prior to version 1.46.0, this value was restricted to the following types:

  • BROWSER
  • DESKTOP
  • LAPTOP
  • MOBILE
  • OTHER
  • SERVER
  • TABLET
  • TV
  • UNKNOWN

In version 1.46.0 and beyond, this value can be any string value you'd like, have fun with it!

refreshToken[x].metaData.resourcesArray<String>Available since 1.67.0

The resource URIs associated with this Refresh Token, per RFC 8707 (Resource Indicators for OAuth 2.0). This field is populated during the authorization code exchange when a resource parameter was provided and validated against the application's oauthConfiguration.authorizedResourceUris.

These values are used as the reference point for resource validation in subsequent refresh token grants and /api/jwt/refresh calls.

refreshToken[x].metaData.scopesArray<String>

The scopes associated with this Refresh Token. These are set at authentication when the Refresh Token is first created.

refreshToken[x].startInstantLong

The instant of the start of this Refresh Token. This value will be used to calculate token expiration.

refreshToken[x].tokenString

The string representation of the encoded Refresh Token. This value should be kept in some sort of secure storage and treated as sensitive information.

refreshToken[x].userIdUUID

The User Id of the user for which this Refresh Token was issued.

Example Response JSON For All Refresh Tokens For a User

{
  "refreshTokens": [
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "insertInstant": 1487971807175,
      "id": "ae19cbd9-a6d5-496c-b195-0ab7069dbd1d",
      "metaData": {
        "device": {
          "description": "Hooli Phone 8GB Work Phone",
          "lastAccessedAddress": "170.152.81.62",
          "lastAccessedInstant": 1487996477628,
          "name": "Richard's Hooli Phone",
          "type": "MOBILE"
        },
        "scopes": [
          "offline_access"
        ]
      },
      "startInstant": 1487971808178,
      "token": "xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc",
      "userId": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
    }
  ]
}