JWTs & Refresh Tokens

Overview

JSON Web Tokens (JWTs) are portable identity tokens. A JWT is issued after completing a Login request and is used to identify a user. JWTs can be used to call various FusionAuth APIs or they can be used to authenticate and authorize your APIs. In this document the term JWT and access token are used interchangeably.

Here’s a presentation discussing how to use JWTs in a microservices architecture:

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.

This API will use a JWT as authentication. See JWT Authentication for examples of how you can send the JWT to FusionAuth.

Request

JWT Authentication
Issue a JWT
GET /api/jwt/issue?applicationId={applicationId}&refreshToken={refreshToken}

Request Parameters

applicationIdUUIDrequired

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

refreshTokenString

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-TenantIdString

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_tokenString

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

Example HTTP Request using cookie

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

Response

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](/docs/apis/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.

Response Body

tokenString

The encoded access token.

refreshTokenString

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.

Example Response JSON

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

Reconcile a JWT Using the External JWT Provider

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

This external JWT Identity Provider flow is not compatible with the hosted login pages. This integration is accessible through our API only.

Additionally, if you are integrating with any of the identity providers for which there is a provided Identity Provider integration (whether specific like Facebook or generic like OIDC), prefer those options over this provider.

In general, you should use the /api/identity-provider/login endpoint of another Identity Provider rather than the External JWT provider if one is available.

Request

No Authentication Required
Reconcile a JWT
POST /api/jwt/reconcile

Request Headers

X-Forwarded-ForString

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-TenantIdString

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

applicationIdUUIDrequired

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.

encodedJWTStringrequiredDEPRECATED

The encoded JWT issued by a third party Identity Provider.

Once available use the data.token parameter instead.

data.tokenStringrequiredAvailable since 1.1.0

The encoded JWT issued by a third party Identity Provider.

identityProviderIdUUIDrequired

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.

ipAddressString

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.descriptionString

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

metaData.device.lastAccessedAddressString

The IP address of this login request.

metaData.device.nameString

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

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!

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

Response

The response for this API contains the User object.

Response Codes

CodeDescription
200The reconcile was successful. The response will contain the User object that was authenticated.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401The 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.
404The user was not found or the password was incorrect. The response will be empty.
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

refreshTokenString

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.

refreshTokenIdStringAvailable 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.

stateObject

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.

tokenStringAvailable since 1.16.0

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

tokenExpirationInstantLongAvailable 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.activeBoolean

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

user.birthDateString

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

user.breachedPasswordLastCheckedInstantLong

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

user.connectorIdUUIDAvailable since 1.18.0

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

user.cleanSpeakIdUUID

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.dataObject

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

user.data.emailString

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 1.27.2.

user.emailString

The User’s email address.

user.expiryLong

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

user.firstNameString

The first name of the User.

user.fullNameString

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

user.idUUID

The User’s unique Id.

user.imageUrlString

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

user.insertInstantLong

The instant when the user was created.

user.lastLoginInstantLong

The instant when the User logged in last.

user.lastNameString

The User’s last name.

user.lastUpdateInstantLong

The instant when the User was last updated.

user.membershipsArray

The list of memberships for the User.

user.memberships[x].dataObject

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

user.memberships[x].groupIdUUID

The Id of the Group of this membership.

user.memberships[x].idUUID

The unique Id of this membership.

user.memberships[x].insertInstantLong

The instant that the membership was created.

user.middleNameString

The User’s middle name.

user.mobilePhoneString

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

user.parentEmailStringAvailable 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.passwordChangeRequiredBoolean

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

user.passwordLastUpdateInstantLong

The instant that the User last changed their password.

user.preferredLanguagesArray<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.registrationsArray

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

user.registrations[x].applicationIdUUID

The Id of the Application that this registration is for.

user.registrations[x].authenticationTokenString

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

user.registrations[x].cleanSpeakIdUUID

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].dataObject

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

user.registrations[x].idUUID

The Id of this registration.

user.registrations[x].insertInstantLong

The instant that this registration was created.

user.registrations[x].lastLoginInstantLong

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

user.registrations[x].preferredLanguagesArray<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].rolesArray<String>

The list of roles that the User has for this registration. The string is the role’s Name not the role’s Id, e.g. admin or user-role.

user.registrations[x].timezoneString

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

user.registrations[x].tokensMap<String,StringDEPRECATED

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].usernameString

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

user.registrations[x].usernameStatusString

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].verifiedBoolean

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

For additional information, see these tutorials:

user.registrations[x].verifiedInstantLongAvailable since 1.48.0

The instant that this registration was verified.

user.tenantIdUUID

The Id of the Tenant that this User belongs to.

user.timezoneString

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.algorithmString

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

user.twoFactor.methods[x].authenticator.codeLengthInteger

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

user.twoFactor.methods[x].authenticator.timeStepInteger

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

user.twoFactor.methods[x].emailString

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

user.twoFactor.methods[x].idString

The unique Id of the method.

user.twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

user.twoFactor.methods[x].methodString

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].mobilePhoneString

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

user.twoFactorDeliveryStringDEPRECATED

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

The possible values are:

  • None
  • TextMessage
Removed in 1.26.0
user.twoFactorEnabledBooleanDEPRECATED

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

Removed in 1.26.0
user.usernameString

The username of the User.

user.usernameStatusString

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.verifiedBoolean

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

For additional information, see these tutorials:

user.verifiedInstantLongAvailable since 1.48.0

The instant that this email address was verified.

Note that this value is immutable and will only represent the first time the email was verified. If you enable re-verification on email change, this value will not change and will only represent the initial verification.

Example Response JSON

{
  "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",
        "verified": true,
        "verifiedInstant": 1698772159415
      }
    ],
    "timezone": "America/Denver",
    "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
    "twoFactor": {
      "methods": [
        {
          "authenticator": {
            "algorithm": "HmacSHA1",
            "codeLength": 6,
            "timeStep": 30
          },
          "id": "35VW",
          "method": "authenticator"
        },
        {
          "id": "V7SH",
          "method": "sms",
          "mobilePhone": "555-555-5555"
        },
        {
          "email": "example@fusionauth.io",
          "id": "7K2G",
          "method": "email"
        }
      ]
    },
    "usernameStatus": "ACTIVE",
    "username": "johnny123",
    "verified": true,
    "verifiedInstant": 1698772159415
  }
}

Response Cookies

access_tokenString

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

refresh_tokenString

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.

Retrieve Public Keys

This API is used to retrieve Public Keys generated by FusionAuth. These can be used to cryptographically verify JWTs signed with the corresponding RSA or ECDSA private key.

Request

No Authentication Required
Retrieve all Public Keys
GET /api/jwt/public-key

Request Headers

X-FusionAuth-TenantIdString

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.

No Authentication Required
Retrieve a single Public Key for a specific Application by Application Id
GET /api/jwt/public-key?applicationId={applicationId}

Request Parameters

applicationIdUUID

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-TenantIdString

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.

This API has been available since 1.8.0

No Authentication Required
Retrieve a single Public Key by Key Identifier
GET /api/jwt/public-key?kid={kid}

Request Parameters

kid

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

Response

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.

Response Body

publicKeysMap<String, String>

The public keys keyed by the kid .

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

Response Body

publicKeyString

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

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.

Request

No Authentication Required
Request a new Access Token by presenting a valid Refresh Token.
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.

Request Headers

X-FusionAuth-TenantIdString

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_tokenString

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_tokenString

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

refreshTokenString

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.

tokenString

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.

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

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}

Request Parameters

tokenIdUUIDrequired

The Id of the token.

Request Headers

X-FusionAuth-TenantIdString

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
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 refresh token specified by the tokenId is missing or revoked.
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

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.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}

Request Parameters

userIdUUIDrequired

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

Request Headers

X-FusionAuth-TenantIdString

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

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

Revoke Refresh Tokens

This can be used to revoke a centrally managed session, when the refresh token is being used to model a session. Learn more about using refresh tokens to model sessions.

Request

API Key Authentication
Revoke all Refresh Tokens for an entire Application
DELETE /api/jwt/refresh?applicationId={applicationId}

Request Parameters

applicationIdUUIDrequired

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-TenantIdString

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.

API Key Authentication
Revoke all Refresh Tokens issued to a User
DELETE /api/jwt/refresh?userId={userId}

Request Parameters

userIdUUIDrequired

The Id of the user to revoke issued Refresh Tokens.

Request Headers

X-FusionAuth-TenantIdString

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.

API Key Authentication
Revoke all Refresh Tokens issued to a User for an Application
DELETE /api/jwt/refresh?applicationId={applicationId}&userId={userId}

Available Since Version 1.19.0

Request Parameters

applicationIdUUIDrequired

The Id of the application.

userIdUUIDrequired

The Id of the user.

Request Headers

X-FusionAuth-TenantIdString

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.

JWT Authentication
Revoke a single Refresh Token by Id
DELETE /api/jwt/refresh/{tokenId}

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

tokenIdUUIDrequired

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.

JWT Authentication
Revoke a single Refresh Token by value
DELETE /api/jwt/refresh?token={token}

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

tokenStringrequired

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-TenantIdString

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

This API does not return a JSON response body.

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.

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.

You can also validate a JWT without using this API call. To do so, validate the JWT attributes and signature locally. Many programming languages have libraries to do this. Here’s an example in Java.

Request

No Authentication Required
Validate Access Token.
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.

Request Headers

AuthorizationString

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_tokenString

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

Response Codes

CodeDescription
200The request was successful. The response will contain a JSON body.
401The 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

jwtObject

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

Vend a JWT

This API is used to create a free-form access token (JWT) with claims defined by the caller. The only “reserved” claims that cannot be specified are exp and iat. The iat claim is the issued at time of the JWT and the exp is the expiration time of the JWT as computed by adding to the iat value either the user passed timeToLiveInSeconds or the tenant JWT timeToLiveInSeconds . If a reserved claim is passed into the claims object, it will be ignored.

This API has been available since 1.30.0

Here’s a video showing how to use this feature.

Request

API Key Authentication
Vend a JWT
POST /api/jwt/vend

Request Headers

X-FusionAuth-TenantIdString

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

claimsObject

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.

keyIdUUID

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.

timeToLiveInSecondsInteger

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.

Example Request JSON

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

Response

Response Codes
Code Description
200 The request was successful. The response will contain a JSON body.
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.
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

tokenString

The encoded access token.

Example Response JSON

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