JWT APIs

1. Overview

JSON Web Tokens (JWTs) are portable identity tokens. A JWT is issued after completing a Login request. In this document the term JWT and access token are used interchangeably.

2. Issue a JWT

This API is used to issue a new access token (JWT) using an existing access token (JWT).

This API provides the single signon mechanism for access tokens. For example you have an access token for application A and you need an access token for application B. You may use this API to request an access token to application B with the authorized token to application A. The returned access token will have the same expiration of the one provided.

2.1. Request

Issue an Access Token

URI

GET /api/jwt/issue?applicationId={applicationId}

Table 1. Request Parameters

applicationId [UUID] Required

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

2.2. Response

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

202

The request was successful. The response will contain a JSON body. The user is not authorized to the requested application, the returned access token will not contain claims for an application. This user is authenticated but not registered.

401

You did not supply a valid Authorization header, the header was omitted or your access token is expired. 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.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 3. Response Body

token [String]

The encoded access token.

Example Response JSON
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODc5NzU0NTgsImlhdCI6MTQ4Nzk3MTg1OCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI4NThhNGIwMS02MmM4LTRjMmYtYmZhNy02ZDAxODgzM2JlYTciLCJhcHBsaWNhdGlvbklkIjoiM2MyMTllNTgtZWQwZS00YjE4LWFkNDgtZjRmOTI3OTNhZTMyIiwicm9sZXMiOlsiYWRtaW4iXX0.O29_m_NDa8Cj7kcpV7zw5BfFmVGsK1n3EolCj5u1M9hZ09EnkaOl5n68OLsIcpCrX0Ue58qsabag3MCNS6H4ldt6kMnH6k4bVg4TvIjoR8WE-yGcu_xDUObYKZYaHWiNeuDL1EuQQI_8HajQLND-c9juy5ILuz6Fhx8CLfHCziEHX_aQPt7jQ2IIasVzprKkgvWS07Hiv2Oskryx49wqCesl46b-30c6nfttHUDEQrVq9gaepca3Nhjj_cPtC400JgLCN9DOYIbtd69zvD8vDUOvVzMr2HGdWtKthqa35NF-3xMZKD8CShe8ZT74fNd9YZ0WRE-YeIf3T_Hv5p5V2w"
}

3. Reconcile a JWT

The Reconcile API is used to take a JWT issued by a third party identity provider as described by an Identity Provider configuration and reconcile the User represented by the JWT to FusionAuth.

3.1. Request

Reconcile a JWT

URI

POST /api/jwt/reconcile

Table 4. 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.

Table 5. 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.

device [String] Optional

The unique device identifier for this request.

Use this parameter to cause a refresh token cookie will be written to the client on the response named refresh_token and it will also be provided in the response body. This value should be unique to the device and the same device id should be sent on subsequent requests for the same device.

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

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

3.2. Response

The response for this API contains the User object.

Table 6. Response Codes
Code Description

200

The reconcile was successful. The response will contain the User object that was authenticated.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

The request cannot be completed. The identityProviderId is invalid, the JWT signature cannot be validated, the JWT does not contain a claim identified by the uniqueIdentityClaim property in the Identity Provider configuration, or the domain of the email address claim in the JWT is not managed by the Identity Provider Configuration.

404

The user was not found or the password was incorrect. 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.

Table 7. Response Body

refreshToken [String]

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

token [String]

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

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.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.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 user was created.

user.lastLoginInstant [Long]

The instant when the User logged in last.

user.lastName [String]

The User’s last name.

user.middleName [String]

The User’s middle name.

user.mobilePhone [String]

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

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.

user.registrations[x].applicationId [UUID]

The Id of the Application that this registration is for.

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.

user.registrations[x].tokens [Map<String,String>] Available Since 1.1.0

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.

user.registrations[x].username [String]

The username of the User for this registration only.

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

The User’s preferred timezone.

users.twoFactorDelivery [String]

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

The possible values are:

  • None

  • TextMessage

user.twoFactorEnabled [Boolean]

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

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.

Example Response JSON
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "user": {
    "active": true,
    "birthDate": "1976-05-30",
    "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"
        ],
        "tokens": {
          "Facebook": "nQbbBIzDhMXXfa7iDUoonz5zS",
          "19544aa2-d634-4859-b193-e57af82b5d12": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp"
        },
        "username": "johnny123",
        "usernameStatus": "ACTIVE"
      }
    ],
    "timezone": "America/Denver",
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true
  }
}
Table 8. Response Cookies

access_token [String]

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

refresh_token [String]

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

4. Retrieve Public Keys

This API is used to retrieve RSA Public Keys used to verify JWT signatures signed using the corresponding RSA private key.

4.1. Request

Retrieve all Public Keys

URI

GET /api/jwt/public-key

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

URI

GET /api/jwt/public-key?applicationId={applicationId}

Table 9. Request Parameters

applicationId [UUID] Optional

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

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

4.2. Response

Table 10. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

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.

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.

Table 11. Response Body for a all Public Keys

publicKeys [Map<String, String>]

The public keys keyed by the Application Id.

There is one special key value named default. If this value exists in the response, this will be the public key that will be used when signing JSON Web Tokens when the Application has not specified its own JWT configuration.

Example Response JSON for all Public Keys
{
  "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"
  }
}
Table 12. Response Body for a single Public Key

publicKey [String]

The public key configured for the specified Application.

Example Response JSON for a single Public Key
{
  "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",
}

5. Refresh a JWT

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

URI

POST /api/jwt/refresh

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.

Table 13. Request Body

refreshToken [String] Optional

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

Example Request JSON
{
  "refreshToken": "xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc"
}
Table 14. Request Cookies

refresh_token [String] Optional

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

Example POST HTTP Request containing Cookie Header
POST /api/jwt/refresh HTTP/1.1
Cookie: refresh_token=xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc

5.1. Response

Table 15. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

The provided Refresh Token is either expired 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.

Table 16. Response Body

token [String]

The encoded access token.

Example Response JSON
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODc5NzU0NTgsImlhdCI6MTQ4Nzk3MTg1OCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI4NThhNGIwMS02MmM4LTRjMmYtYmZhNy02ZDAxODgzM2JlYTciLCJhcHBsaWNhdGlvbklkIjoiM2MyMTllNTgtZWQwZS00YjE4LWFkNDgtZjRmOTI3OTNhZTMyIiwicm9sZXMiOlsiYWRtaW4iXX0.O29_m_NDa8Cj7kcpV7zw5BfFmVGsK1n3EolCj5u1M9hZ09EnkaOl5n68OLsIcpCrX0Ue58qsabag3MCNS6H4ldt6kMnH6k4bVg4TvIjoR8WE-yGcu_xDUObYKZYaHWiNeuDL1EuQQI_8HajQLND-c9juy5ILuz6Fhx8CLfHCziEHX_aQPt7jQ2IIasVzprKkgvWS07Hiv2Oskryx49wqCesl46b-30c6nfttHUDEQrVq9gaepca3Nhjj_cPtC400JgLCN9DOYIbtd69zvD8vDUOvVzMr2HGdWtKthqa35NF-3xMZKD8CShe8ZT74fNd9YZ0WRE-YeIf3T_Hv5p5V2w"
}
Table 17. Response Cookies

access_token [String]

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

6. Retrieve Refresh Tokens

Retrieve Refresh Tokens issued to a User

URI

GET /api/jwt/refresh?userId={userId}

Table 18. Request Parameters

userId [UUID] Required

The Id of the user to retrieve issued Refresh Tokens.

Retrieve Refresh Tokens issued to a User

URI

GET /api/jwt/refresh

6.1. Response

Table 19. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

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.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 20. Response Body

refreshTokens [Array]

An array of Refresh Tokens

refreshTokens[x]applicationId [String]

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

refreshTokens[x]device [String]

A unique device identifier to represent the device for which this Refresh Token was issued.

refreshTokens[x]insertInstant [String]

The instant this Refresh Token was issued.

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

A description of the device. For example, iPhone 6S 32GB Work Phone.

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

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

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

The name of the device, for example Mary’s iPhone.

refreshTokens[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

refreshTokens[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.

refreshTokens[x]userId [UUID]

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

Example Response JSON
{
  "refreshTokens": [
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "device": "_mymobile_f47dW",
      "insertInstant": 1487971807175,
      "metaData": {
        "device": {
          "lastAccessedAddress": "170.152.81.62",
          "lastAccessedInstant": 1487996477628,
          "type": "MOBILE"
        }
      },
      "token": "xRxGGEpVawiUak6He367W3oeOfh+3irw+1G1h1jc",
      "userId": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
    }
  ]
}

7. Revoke Refresh Tokens

Revoke all Refresh Tokens for an entire Application

URI

DELETE /api/jwt/refresh?applicationId={applicationId}

Table 21. 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.

Revoke all Refresh Tokens issued to a User

URI

DELETE /api/jwt/refresh?userId={userId}

Table 22. Request Parameters

userId [UUID] Required

The Id of the user to revoke issued Refresh Tokens.

Revoke a single Refresh Token

URI

DELETE /api/jwt/refresh?token={token}

This API may be authenticated using an Access Token. See Authentication for examples of authenticating using an Access Token. The token owner must match the identity in the access token if provided to be successful.

Table 23. 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.

7.1. Response

This API does not return a JSON response body.

Table 24. Response Codes
Code Description

200

The request was successful. The response will be empty.

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.

404

The object you are trying to delete 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.

8. Validate a JWT

This API is used to validate a JSON Web Token. A valid JWT indicates the signature is valid and the payload has not be tampered with and the token is not expired.

8.1. Request

Validate Access Token.

URI

GET /api/jwt/validate

The access token can be provided to the API using an HTTP request header, or a cookie. The response body will contain the decoded JWT payload.

Table 25. 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: JWT <encoded_access_token>

See Authentication for additional examples.

Table 26. Request Cookies

access_token [String] Optional

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

Table 27. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

401

The access token is not valid. A new access token may be obtained by authentication against the Login API, the Token Endpoint or by utilizing a Refresh Token.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Table 28. Response Body

jwt [Object]

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

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