JWT & Refresh Token APIs

Request Parameters

applicationId [UUID] Required

The Id of the application for which authorization is being requested.

refreshToken [String] Optional

An existing refresh token used to request a refresh token in addition to a JWT in the response. If the cookie refresh_token is also on the request it will take precedence over this value.

The target application represented by the applicationId request parameter must have refresh tokens enabled in order to receive a refresh token in the response.

Request Headers

X-FusionAuth-TenantId [String] Optional

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_token [String] Optional

The refresh token to be used to exchange for a refresh token in the application represented by the applicationId request parameter.

GET /api/jwt/issue HTTP/1.1
Cookie: refresh_token=xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc

Response Body

token [String]

The encoded access token.

refreshToken [String]

The refresh token. This value will only be returned if a valid non-expired refresh token was provided on the request and application.loginConfiguration.generateRefreshTokens is true. The returned refresh token will share the same creation time as the original refresh token in regards to how the token expiration is calculated.

The refresh token expiration policy as defined by jwtConfiguration.refreshTokenExpirationPolicy must be the same as the source application, if the policies are different a refresh token will not be returned.

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODc5NzU0NTgsImlhdCI6MTQ4Nzk3MTg1OCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI4NThhNGIwMS02MmM4LTRjMmYtYmZhNy02ZDAxODgzM2JlYTciLCJhcHBsaWNhdGlvbklkIjoiM2MyMTllNTgtZWQwZS00YjE4LWFkNDgtZjRmOTI3OTNhZTMyIiwicm9sZXMiOlsiYWRtaW4iXX0.O29_m_NDa8Cj7kcpV7zw5BfFmVGsK1n3EolCj5u1M9hZ09EnkaOl5n68OLsIcpCrX0Ue58qsabag3MCNS6H4ldt6kMnH6k4bVg4TvIjoR8WE-yGcu_xDUObYKZYaHWiNeuDL1EuQQI_8HajQLND-c9juy5ILuz6Fhx8CLfHCziEHX_aQPt7jQ2IIasVzprKkgvWS07Hiv2Oskryx49wqCesl46b-30c6nfttHUDEQrVq9gaepca3Nhjj_cPtC400JgLCN9DOYIbtd69zvD8vDUOvVzMr2HGdWtKthqa35NF-3xMZKD8CShe8ZT74fNd9YZ0WRE-YeIf3T_Hv5p5V2w",
  "refreshToken": "YRjxLpsjRqL7zYuKstXogqioA_P3Z4fiEuga0NCVRcDSc8cy_9msxg"
}

Request Headers

X-Forwarded-For [String] Optional

The IP address of a client requesting authentication. If the IP address is provided it will be stored for login history of the user. It is generally preferred to specify the IP address in the request body. If it is not provided in the request body this header value will be used if available, the request body value will take precedence.

X-FusionAuth-TenantId [String] Optional

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 Body

applicationId [UUID] Required

The Id of the Application the User will be logged into during the reconcile process. If the User is not already registered to this Application they will be registered and be assigned any roles identified as default.

If this value is not a valid Application Id, a 401 will be returned.

encodedJWT [String] Required Deprecated

The encoded JWT issued by a third party Identity Provider.

Once available use the data.token parameter instead.

data.token [String] Required Available since 1.1.0

The encoded JWT issued by a third party Identity Provider.

identityProviderId [UUID] Required

The unique Id of the Identity Provider to utilize when reconciling the JWT.

If this value is not a valid Identity Provider Id, a 401 will be returned.

ipAddress [String] Optional

The IP address of the end-user that is logging into FusionAuth. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the X-Forwarded-For header if provided or the last proxy that sent the request. The IP address will be stored in the User login history.

metaData.device.description [String] Optional

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

metaData.device.lastAccessedAddress [String] Optional

The IP address of this login request.

metaData.device.name [String] Optional

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

metaData.device.type [String] Optional

The type of device represented by the device parameter. The following types may be specified:

• BROWSER

• DESKTOP

• LAPTOP

• MOBILE

• OTHER

• SERVER

• TABLET

• TV

• UNKNOWN

{
  "applicationId": "ff9880a1-74fd-4947-b482-1ca6f9788362",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo"
  },
  "identityProviderId": "0c5ecd6e-a55f-4d3c-8236-f26a966392ea",
  "ipAddress": "192.168.1.42"
}

Response Body

refreshToken [String]

The refresh token that can be used to obtain a new access token once the provided one has expired.

Because a refresh token is per user and per application, this value will only be returned when an applicationId was provided on the login request and the user is registered to the application.

You must explicitly allow generation of refresh tokens when using the Login API. Configure the application.loginConfiguration.generateRefreshTokens setting via the API or enable the setting by navigating to the Application → My Application → Security tab.

refreshTokenId [String] Available since 1.37.0

When the refreshToken is returned in the response, this field will also be returned. 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.

state [Object]

If authenticated using a One Time Password and state was provided during the Change Password request this value will be returned exactly as it was provided.

token [String] Available since 1.16.0

The access token, this string is an encoded JSON Web Token (JWT).

tokenExpirationInstant [Long] Available since 1.33.0

The instant the token will expire. If the response does not contain a token, this field will also be omitted from the response.

user.active [Boolean]

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

user.birthDate [String]

The User’s birthdate formatted as YYYY-MM-DD

user.breachedPasswordLastCheckedInstant [Long]

The instant this user’s password was last checked to determine if it is compromised.

user.connectorId [UUID] Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

user.cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.data [Object]

An object that can hold any information about the User that should be persisted.

user.data.email [String]

This field will be used as the email address if no user.email field is found.

This feature was removed in version 1.26.0 and added back in in 1.27.2.

user.email [String]

The User’s email address.

user.expiry [Long]

The expiration instant of the User’s account. An expired user is not permitted to login.

user.firstName [String]

The first name of the User.

user.fullName [String]

The User’s full name as a separate field that is not calculated from firstName and lastName.

user.id [UUID]

The User’s unique Id.

user.imageUrl [String]

The URL that points to an image file that is the User’s profile image.

user.insertInstant [Long]

The instant when the user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.lastUpdateInstant [Long]

The instant when the User was last updated.

user.memberships [Array]

The list of memberships for the User.

user.memberships[x].data [Object]

An object that can hold any information about the User for this membership that should be persisted.

user.memberships[x].groupId [UUID]

The Id of the Group of this membership.

user.memberships[x].id [UUID]

The unique Id of this membership.

user.memberships[x].insertInstant [Long]

The instant that the membership was created.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

The User’s mobile phone number. This is useful if you will be sending push notifications or SMS messages to the User.

user.parentEmail [String] Available since 1.7.0

The email address of the user’s parent or guardian. If this value was provided during a create or update operation, this value will only remain until the child is claimed by a parent.

user.passwordChangeRequired [Boolean]

Indicates that the User’s password needs to be changed during their next login attempt.

user.passwordLastUpdateInstant [Long]

The instant that the User last changed their password.

user.preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

user.registrations [Array]

The list of registrations for the User. This will include registrations for inactive applications.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

user.registrations[x].authenticationToken [String]

The Authentication Token for this registration (if one exists).

user.registrations[x].cleanSpeakId [UUID]

This Id is used by FusionAuth when the User’s username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

user.registrations[x].data [Object]

An object that can hold any information about the User for this registration that should be persisted.

user.registrations[x].id [UUID]

The Id of this registration.

user.registrations[x].insertInstant [Long]

The instant that this registration was created.

user.registrations[x].lastLoginInstant [Long]

The instant that the User last logged into the Application for this registration.

user.registrations[x].preferredLanguages [Array<String>]

An array of locale strings that give, in order, the User’s preferred languages for this registration. These are important for email templates and other localizable text.

user.registrations[x].roles [Array<String>]

The list of roles that the User has for this registration.

user.registrations[x].timezone [String]

The User’s preferred timezone for this registration. The string will be in an IANA time zone format.

user.registrations[x].tokens [Map<String,String>] Deprecated

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

user.registrations[x].username [String]

The username of the User for this registration only. This is for display purposes and cannot be used to login.

user.registrations[x].usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.registrations[x].verified [Boolean]

This value indicates if this User’s registration has been verified.

For additional information, see these tutorials:

• Email Verification

• Registration Verification

user.tenantId [UUID]

The Id of the Tenant that this User belongs to.

user.timezone [String]

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow Users to change this per-session. The string will be in an IANA time zone format.

user.twoFactor.methods[x].authenticator.algorithm [String]

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

user.twoFactor.methods[x].authenticator.codeLength [Integer]

The length of code generated by the TOTP. With the current implementation, this will always be 6.

user.twoFactor.methods[x].authenticator.timeStep [Integer]

The time-step size in seconds. With the current implementation, this will always be 30.

user.twoFactor.methods[x].email [String]

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

user.twoFactor.methods[x].id [String]

The unique Id of the method.

user.twoFactor.methods[x].lastUsed [Boolean]

true if this method was used most recently.

user.twoFactor.methods[x].method [String]

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

• authenticator

• email

• sms

user.twoFactor.methods[x].mobilePhone [String]

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

user.twoFactor.methods[x].secret [String]

A base64 encoded secret

user.twoFactorDelivery [String] Deprecated

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

• None

• TextMessage

  Removed in version 1.26.0

user.twoFactorEnabled [Boolean] Deprecated

Determines if the User has two factor authentication enabled for their account or not.

Removed in version 1.26.0

user.username [String]

The username of the User.

user.usernameStatus [String]

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

• ACTIVE - the username is active

• PENDING - the username is pending approval/moderation

• REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

user.verified [Boolean]

Whether or not the User’s email has been verified.

For additional information, see these tutorials:

• Email Verification

• Registration Verification

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
    "data": {
      "displayName": "Johnny Boy",
      "favoriteColors": [
        "Red",
        "Blue"
      ]
    },
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "firstName": "John",
    "fullName": "John Doe",
    "id": "00000000-0000-0001-0000-000000000000",
    "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
    "lastLoginInstant": 1471786483322,
    "lastName": "Doe",
    "middleName": "William",
    "mobilePhone": "303-555-1234",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "preferredLanguages": [
      "en",
      "fr"
    ],
    "registrations": [
      {
        "applicationId": "10000000-0000-0002-0000-000000000001",
        "data": {
          "displayName": "Johnny",
          "favoriteSports": [
            "Football",
            "Basketball"
          ]
        },
        "id": "00000000-0000-0002-0000-000000000000",
        "insertInstant": 1446064706250,
        "lastLoginInstant": 1456064601291,
        "preferredLanguages": [
          "en",
          "fr"
        ],
        "roles": [
          "user",
          "community_helper"
        ],
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}

Response Cookies

access_token [String]

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

refresh_token [String]

The refresh token. This cookie is written in the response as an HTTPOnly persistent cookie. The cookie expiration is configured in the JWT configuration for the application or the global JWT configuration.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Retrieve a single Public Key for a specific Application by Application Id

Request Parameters

applicationId [UUID] Optional

The Application Id is used to retrieve a specific Public Key. This will return the Public Key that has been specifically configured for the provided Application to sign the access token.

A public key may not be available for an Application if it is configured to use the global JWT configuration or a HMAC is the configured algorithm for JWT signing.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Retrieve a single Public Key by Key Identifier

Request Parameters

kid [String Optional

The Key Id used to retrieve a specific Public Key. This will return the Public Key associated with the Key Id.

Response Body

publicKeys [Map<String, String>]

The public keys keyed by the kid.

{
  "publicKeys": {
    "4ed5eb32-0a97-40eb-a6d7-cca1f9fa3a0c": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAjocc7+h63/jSkxnT0eaNY\nx1CAKtTB3oIUd6IfxXLdbhHtt7dwtOVkSMxSXR7232ZxFN52iITL6IJNEmq7vrOPd\ndIAlS5qakwqwRR7zaH73dn3JHfDdGI3CJ4/sHbFZZztXTElU44kglbuQv+2QVEHM5\nwLLf4abUWrndjDokgVWzQukTovnS7YgvKcEsgfQDouH6lMnIw/+fXFEA+NWKK/HcX\nMmd2G98DSWUXC1dbwOj9LsPs2Jp4rksjxkzb4SLbq5Lnx22DxfURg7EQtufhr1CO8\nXuw8fA52h0xnZmbVh3zeASe6lf8hY21nPuB+Ih7gIgrUq45P020/KvdfjgKnau980\nMzuxr2DcNOKXDoNUoPys6mOQIINRE+v5Rxbekf758E+OGJjc/8uok8BmAWrolorJO\nwMKpRAnI2M523Pf4czjtz7k2E4LKGs/9UKWlCGgobQ5gwc4ZkkUgk1wx6vjCzXmFH\nkR6U6NvoXs6RBKEptSHN2uIhNNxiin2I/42JWb6kZhtDU88bC6wUwpKEVOrKlFhT0\ne9kelXHPxAq93i+rDomhMMqrZLARAZ+hA7yblN6RlMRlDoiuusG3C/NsqdNZM919r\njo+uymdkfsn07QSWWoLZzxhuyMcDUqWOn9kqbGUQKI+RVT3JNNuggMP7kpGIEobHL\n6PER9atthGjUCAwEAAQ==\n-----END PUBLIC KEY-----\n",
    "default": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnwDYDEUJT9OweW0WG/6tV\nF7MpOJBAvyiyPXaewDvTS5D+2Nop4Ur0VSBrCpeQGT2zaxhGZsqGDlHsPT9vdjSn5\nk55Vu+YWKkv6kcjZNrYtF9tY18BMWeld8WrhQP/P1vQWLHst71LgpvAK3VBWEMZ6l\n/x/i0vzX8HrOBJwxDVZ5r3WjbXIvM7OJ4qf3bQnjRTf/Hps2+LnDIK3u3xrNqtMgU\noY++lNZi0EuFRaKLaAPnynEF2XHaNazv2hHl243aTSXXJIoal54N8BgtXycLVanDL\nD2TfEEKib/p1750tNKB810LiNbiNbEeNO0XQr500ulOEZzVJY5zCmbCaHmPlwIDAQ\nAB\n-----END PUBLIC KEY-----\n"
  }
}

Response Body

publicKey [String]

The public key configured for the specified Application.

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAjocc7+h63/jSkxnT0eaNY\nx1CAKtTB3oIUd6IfxXLdbhHtt7dwtOVkSMxSXR7232ZxFN52iITL6IJNEmq7vrOPd\ndIAlS5qakwqwRR7zaH73dn3JHfDdGI3CJ4/sHbFZZztXTElU44kglbuQv+2QVEHM5\nwLLf4abUWrndjDokgVWzQukTovnS7YgvKcEsgfQDouH6lMnIw/+fXFEA+NWKK/HcX\nMmd2G98DSWUXC1dbwOj9LsPs2Jp4rksjxkzb4SLbq5Lnx22DxfURg7EQtufhr1CO8\nXuw8fA52h0xnZmbVh3zeASe6lf8hY21nPuB+Ih7gIgrUq45P020/KvdfjgKnau980\nMzuxr2DcNOKXDoNUoPys6mOQIINRE+v5Rxbekf758E+OGJjc/8uok8BmAWrolorJO\nwMKpRAnI2M523Pf4czjtz7k2E4LKGs/9UKWlCGgobQ5gwc4ZkkUgk1wx6vjCzXmFH\nkR6U6NvoXs6RBKEptSHN2uIhNNxiin2I/42JWb6kZhtDU88bC6wUwpKEVOrKlFhT0\ne9kelXHPxAq93i+rDomhMMqrZLARAZ+hA7yblN6RlMRlDoiuusG3C/NsqdNZM919r\njo+uymdkfsn07QSWWoLZzxhuyMcDUqWOn9kqbGUQKI+RVT3JNNuggMP7kpGIEobHL\n6PER9atthGjUCAwEAAQ==\n-----END PUBLIC KEY-----\n"
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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_token [String] Optional

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_token [String] Optional

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

refreshToken [String] Optional

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.

token [String] Optional

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.

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

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 Body

refreshToken [String]

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.

refreshTokenId [String] Available 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.

token [String]

The encoded access token.

{
  "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_token [String]

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

refresh_token [String]

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.

Request Parameters

tokenId [UUID] Required

The Id of the token.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Retrieve Refresh Tokens issued to a User

Request Parameters

userId [UUID] Required

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

Request Headers

X-FusionAuth-TenantId [String] Optional

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 Body

refreshToken.applicationId [String]

The Id of the Application for which this token is authorized to be exchanged for a new Access Token.

refreshToken.insertInstant [Long]

The instant this Refresh Token was issued.

refreshToken.id [UUID]

The Id of the Refresh Token.

refreshToken.metaData.device.description [String]

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

refreshToken.metaData.device.lastAccessedAddress [String]

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

refreshToken.metaData.device.lastAccessedInstant [Long]

The instant this Refresh Token was last used.

refreshToken.metaData.device.name [String]

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

refreshToken.metaData.device.type [String]

The type of device represented by the device parameter. The following are possible types:

• BROWSER

• DESKTOP

• LAPTOP

• MOBILE

• OTHER

• SERVER

• TABLET

• TV

• UNKNOWN

refreshToken.metaData.scopes [Array<String>]

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

refreshToken.startInstant [Long]

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

refreshToken.token [String]

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.userId [UUID]

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

{
  "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"
  }
}

Response Body

refreshTokens [Array]

An array of Refresh Tokens

refreshToken[x].applicationId [String]

The Id of the Application for which this token is authorized to be exchanged for a new Access Token.

refreshToken[x].insertInstant [Long]

The instant this Refresh Token was issued.

refreshToken[x].id [UUID]

The Id of the Refresh Token.

refreshToken[x].metaData.device.description [String]

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

refreshToken[x].metaData.device.lastAccessedAddress [String]

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

refreshToken[x].metaData.device.lastAccessedInstant [Long]

The instant this Refresh Token was last used.

refreshToken[x].metaData.device.name [String]

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

refreshToken[x].metaData.device.type [String]

The type of device represented by the device parameter. The following are possible types:

• BROWSER

• DESKTOP

• LAPTOP

• MOBILE

• OTHER

• SERVER

• TABLET

• TV

• UNKNOWN

refreshToken[x].metaData.scopes [Array<String>]

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

refreshToken[x].startInstant [Long]

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

refreshToken[x].token [String]

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].userId [UUID]

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

{
  "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"
    }
  ]
}

Request Parameters

applicationId [UUID] Required

The Id of the application to revoke all issued Refresh Tokens. This will result in any user issued a Refresh Token for this application being required to be issued a new Refresh Token, in other words they’ll need to be authenticated again.

This essentially provides a kill switch for all Refresh Tokens scoped to the application.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Revoke all Refresh Tokens issued to a User

Request Parameters

userId [UUID] Required

The Id of the user to revoke issued Refresh Tokens.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Revoke all Refresh Tokens issued to a User for an Application

Request Parameters

applicationId [UUID] Required

The Id of the application.

userId [UUID] Required

The Id of the user.

Request Headers

X-FusionAuth-TenantId [String] Optional

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.

Revoke a single Refresh Token by Id

This API may be authenticated using a JWT or an API key. If using JWT authentication, the JWT owner and token owner must match. See Authentication for examples of authenticating using a JWT.

Request Parameters

tokenId [UUID] Required

The Id of the refresh token to be revoked.

When deleting a single token, using this parameter is recommended. Using this parameter does not expose the refresh token.

Revoke a single Refresh Token by value

This API may be authenticated using a JWT or an API key. If using JWT authentication, the JWT owner and token owner must match. See Authentication for examples of authenticating using a JWT.

Request Parameters

token [String] Required

The refresh token in string form that is to be revoked. This string may contain characters such as a plus sign that need to be encoded to be valid on the URL. If you’re manually building this request ensure you are properly URL encoding this value.

You can also pass the refresh token in the HTTP body by specifying a Content-Type header of application/x-www-form-urlencoded and providing the proper URL encoded value for the parameter. This will prevent the refresh token from being written to HTTP access logs.

If possible, it is recommended use the tokenId parameter rather than this one.

Request Headers

X-FusionAuth-TenantId [String] Optional

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 Headers

Authorization [String] Optional

The encoded JWT to validate sent in on the Authorization request header.

The header is expected be in the following form: Authorization: Bearer <encoded_access_token>.

See Authentication for additional examples.

Request Cookies

access_token [String] Optional

The encoded JWT. This cookie is written to the client by the Login API.

Response Body

jwt [Object]

The decoded JWT payload. The payload contains the identity claims for the user.

{
  "jwt": {
    "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
    "exp": 1487975407000,
    "iat": 1487971807000,
    "iss": "acme.com",
    "roles": [
      "admin"
    ],
    "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
  }
}

Request Headers

X-FusionAuth-TenantId [String] Optional

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 Body

claims [Object] Optional

A set of claims to add to this JWT. If any of the "reserved" claims, exp or iat, are specified they will be ignored. Otherwise, the claims can be any valid JSON value.

keyId [UUID] Optional

The Id of the signing key to use when signing this JWT. If this is not supplied, the tenant’s JWT access token signing key will be used.

timeToLiveInSeconds [Integer] Optional

The length of time in seconds before the JWT expires and is no longer valid. Any integer value greater than 0 is allowed. If omitted, the tenant’s timeToLiveInSeconds value will be used instead.

{
  "claims": {
    "id": "c74aa258-3a04-4d3f-83c5-e5b20af96e7a",
    "iss": "piedpiper.com"
  },
  "keyId": "fafdc79b-d058-4e93-99d9-759e40b03711",
  "timeToLiveInSeconds": 300
}

Response Body

token [String]

The encoded access token.

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6InlQaUx5SGFRZV9YcUVqdHZfQTlrcXNkQndoamV6WXZ2In0.eyJleHAiOjE2Mjk4NDAwOTEsImlhdCI6MTYyOTgzOTc5MSwiaXNzIjoicGllZHBpcGVyLmNvbSIsImp0aSI6ImQ5NWJiMDgxLTFmOWQtNGVjNS05OTk2LTc0YTQwMmMwMzYxNSIsImlkIjoiYzc0YWEyNTgtM2EwNC00ZDNmLTgzYzUtZTViMjBhZjk2ZTdhIn0.3P0PTU7opCmqNmRTC54KmIPIbk6WH3zE9OtIKgA8-fqQluurgKzmqHXiTwsfpuRV2p28s8KvoWbtS0y-zG32Dg"
}