Import Refresh Tokens

Available Since Version 1.19.0

This API is used to import refresh tokens from an external system, this would generally be done during an initial user import or as an auxiliary step during a migration strategy.

Before using this API, create the Users, Applications and User Registrations. A validation error will be returned if the user does not exist, or is not registered for the application.

Request#

Import Refresh Tokens

POST/api/user/refresh-token/import

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

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

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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 Body#

refreshTokensArrayrequired

The list of refresh tokens to import.

refreshTokens[x].applicationIdUUIDrequired

The unique Application Id that corresponds to the User Registration for this refresh token.

refreshTokens[x].metaData.device.descriptionStringoptional

A human readable description of the device represented by the device parameter.

refreshTokens[x].metaData.device.lastAccessedAddressStringoptional

The IP address of this login request.

refreshTokens[x].metaData.device.lastAccessedInstantLongoptional

The instant of this login request.

refreshTokens[x].metaData.device.nameStringoptional

A human readable name of the device represented by the device parameter.

refreshTokens[x].metaData.device.typeStringoptional

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!

refreshTokens[x].startInstantStringrequired

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

refreshTokens[x].tokenStringrequired

The string representation of the refresh token.

Prior to version 1.33.0, this value was limited to a maximum length of 191 characters. If you need to import a token that is longer than 191 characters, ensure you have upgraded to version 1.33.0 or later.

refreshTokens[x].userIdUUIDrequired

The unique user Id of the refresh token owner.

validateDbConstraintsBooleanoptionalDefaults to false

Set this value to true in order to perform additional validation of the request. This validation includes, among other things, confirming that a user exists and is registered for the application which this refreshToken was created for.

If this is false, any errors such as duplicated refresh token values will return a 500 error without any additional messages. If this is true, additional validation will be performed on the input request and a 400 response will be returned with a JSON body indicating duplicate values or other error conditions encountered.

Setting this value to true will dramatically decrease the performance of this request. If importing large numbers of tokens in a single request you may need to increase request timeouts to ensure this request does not timeout before it has completed.

Example Request JSON

{
  "refreshTokens": [
    {
      "applicationId": "18a054da-f72d-480d-8da5-1f17d63bda87",
      "metaData": {
        "device": {
          "description": "My refresh token imported from Umbrella Corp.",
          "lastAccessedAddress": "42.42.42.42",
          "lastAccessedInstant": 1598315358855,
          "name": "John's iPad",
          "type": "TABLET"
        }
      },
      "startInstant": 1598315358855,
      "token": "YRjxLpsjRqL7zYuKstXogqioA_P3Z4fiEuga0NCVRcDSc8cy_9msxg",
      "userId": "e2b25780-fe20-4a69-ab6f-5e84744bc959"
    }
  ]
}

Response#

The response does not contain a body, the HTTP status code will indicate the result of the request.

Response Codes

Code	Description
200	The request was successful.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You 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.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.