Token API

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

This value must be set to application/x-www-form-urlencoded.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this header or the tenantId body parameter.

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required. Prior to version 1.3.1 this parameter was always required.

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

The authorization code returned on the /oauth2/authorize response.

The code_verifier parameter as described in the Proof Key for Code Exchange by OAuth Public Clients (PKCE) specification.

This parameter is required to complete this request when the code_challenge parameter was provided on the initial Authorize request.

The grant type to be used. This value must be set to authorization_code

The URI to redirect to upon a successful request. This URI must have been configured previously in the FusionAuth Application OAuth configuration. See Applications in the FusionAuth User Guide for additional information on configuring the redirect URI.

The URI of the target resource server, per RFC 8707 (Resource Indicators for OAuth 2.0).

To provide multiple URIs, pass each URI as a separate parameter with the same name. The following validation rules are applied in order; any failure returns invalid_target and the authorization code is immediately invalidated:

1. If at least one resource URI from the authorize request is still present in the application's oauthConfiguration.authorizedResourceUris, then at least one resource value is required here.
2. Each provided value must be present in the application's oauthConfiguration.authorizedResourceUris.
3. Each provided value must have also been present in the original authorize request.

When a valid resource is resolved, the issued access token's aud claim is set to ["client_id", "https://resource1.example.com", ...]. When no resource is involved, aud remains a plain string containing only the client_id.

The validated resource URIs are also stored in the refresh token's metaData.resources field for use in subsequent refresh token grants.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this body parameter or the X-FusionAuth-TenantId header.

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

This value must be set to application/x-www-form-urlencoded.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this header or the tenantId body parameter.

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required. Prior to version 1.3.1 this parameter was always required.

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

The grant type to be used. This value must be set to password

A human readable description of the device used during login. This metadata is used to describe the refresh token that may be generated for this login request.

For example:

Erlich's iPhone

A human readable description of the device used during login. This metadata is used to name the refresh token that may be generated for this login request.

For example:

iOS Safari

The type of device represented by the device parameter. This metadata is used to describe the type of device represented by the refresh token that may be generated for this login request.

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!

The login identifier of the user. The login identifier can be either the email or the username.

The user's password.

The optional scope you are requesting during this grant. This parameter may contain multiple space separated scopes. For example, the value of openid offline_access provides two scopes on the request.

Available scopes:

• openid - This scope is used to request an id_token be returned in the response
• offline_access - This scope scope is used to request a refresh_token be returned in the response

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this body parameter or the X-FusionAuth-TenantId header.

The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow.

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

This value must be set to application/x-www-form-urlencoded.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this header or the tenantId body parameter.

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required.

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

The grant type to be used. This value must be set to urn:ietf:params:oauth:grant-type:device_code

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this body parameter or the X-FusionAuth-TenantId header.

The OAuth access token as described by RFC 6749 Section 1.4. See the OAuth Tokens documentation for more information.

The time in seconds the token will expire from the time the response was generated.

The OpenID Id Token. This token is represented as a JSON Web Token (JWT). See the OAuth Tokens documentation for more information.

This field will be returned in the response when openid scope was requested.

The refresh token as described by RFC 6749 Section 1.5

This field will be returned in the response when offline_access scope was requested unless refresh tokens have been disabled for this application. Whether a refresh token is allowed for an application can be controlled by the oauthConfiguration.generateRefreshTokens field in the Application API or the Generate refresh tokens toggle in the FusionAuth admin UI.

The unique Id of the refresh token. This Id can be used to retrieve or revoke a specific refresh token using the Refresh Token API.

This field will be returned when the offline_access scope was requested and refresh tokens are allowed for this application. Whether a refresh token is allowed for an application can be controlled by the oauthConfiguration.generateRefreshTokens field in the Application API or the Generate refresh tokens toggle in the FusionAuth admin UI.

The space-separated list of scopes allowed by the user during the grant which generated this access token. This will only be present for Authorization Code and Password grants.

The token type as defined by RFC 6749 Section 7.1. This value will be Bearer or DPoP if a DPoP Proof was provided.

The unique Id of the user that has been authenticated. This user Id may be used to retrieve the entire user object using the /api/user API.

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. If both the cookie and request body field are provided, the cookie will take precedence.

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

This value must be set to application/x-www-form-urlencoded.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this header or the tenantId body parameter.

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.

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required. Prior to version 1.3.1 this parameter was always required.

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

The expiration time, in seconds, for the access and Id tokens (if the openid scope was included) that will be returned in the response.

When provided on the request, this value will override the default TTL, provided it is less than the default value. The default TTL is taken from application.jwtConfiguration.timeToLiveInSeconds if it is set there, otherwise it is taken from tenant.jwtConfiguration.timeToLiveInSeconds.

The grant type to be used. This value must be set to refresh_token

The refresh token that you would like to use to exchange for an access token.

The URI of the target resource server, per RFC 8707 (Resource Indicators for OAuth 2.0).

To provide multiple URIs, pass each URI as a separate parameter with the same name. Behavior depends on the application's oauthConfiguration.authorizedResourceUris:

• When oauthConfiguration.authorizedResourceUris is empty, this parameter is silently ignored.
• When omitted and oauthConfiguration.authorizedResourceUris is non-empty, the resource URIs stored in the refresh token's metaData.resources from the original authorization are automatically applied to the new access token.
• When provided, each value must be present in both the application's oauthConfiguration.authorizedResourceUris and the refresh token's metaData.resources (i.e. must be a subset of what was authorized originally). Any invalid value returns invalid_target.

The aud claim follows the same rules as the authorization code exchange: an array ["client_id", "https://resource1.example.com", ...] when resources are active, or a plain string client_id when they are not.

This parameter is optional and if omitted, the same scope requested during the authorization request will be used. If provided, the scopes must be a space-delimited subset of those requested during the initial authorization request. The refresh token maintains the set of scopes from the initial authorization request even if a subset of scopes is requested during a Refresh Token Grant.

Prior to version 1.50.0 the scopes must match those requested during the initial authorization request if provided.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this body parameter or the X-FusionAuth-TenantId header.

The end-user verification code. This code is required if using this endpoint to approve the Device Authorization.

The OAuth access token as described by RFC 6749 Section 1.4. See the OAuth Tokens documentation for more information.

The time in seconds the token will expire from the time the response was generated.

The OpenID Id Token. This token is represented as a JSON Web Token (JWT). See the OAuth Tokens documentation for more information.

This field will be returned in the response when openid scope was requested during the initial authentication request when the refresh token was generated.

The token type as defined by RFC 6749 Section 7.1. This value will be Bearer or DPoP if a DPoP Proof was provided.

The unique Id of the user that has been authenticated. This user Id may be used to retrieve the entire user object using the /api/user API.

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

This value must be set to application/x-www-form-urlencoded.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this header or the tenantId body parameter.

The unique client identifier. The client Id is the Id of the FusionAuth Entity in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is required.

The client secret of the Entity. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

The grant type to be used. This value must be set to client_credentials

This parameter is optional. This is a space delimited set of the requested scopes for this grant request.

You will typically provide a scope specifying the target entity:

target-entity:92dbded-30af-4149-9c61-b578f2c72600

You may provide append a comma separated list of permissions as well:

target-entity:92dbded-30af-4149-9c61-b578f2c72600:read,write

You may combine multiple entities and permissions in the same scope parameter:

target-entity:92dbded-30af-4149-9c61-b578f2c72600:read,write target-entity:119a84d9-06c5-4d1f-a0d4-a60490b70ac5:read

Permissions associated with the grant from the target entity to the recipient entity will be available in the permissions claim in the token. If specific permissions are requested, the recipient entity must have previously been granted all of those permissions for a successful access request. If specific permissions are requested, only the requested permissions will be in the permissions claim, otherwise all permissions will be available in that claim.

The Tenant to which this token belongs. When working with a token for a universal application, you must specify a Tenant ID using either this body parameter or the X-FusionAuth-TenantId header.

The OAuth access token as described by RFC 6749 Section 1.4. See the OAuth Tokens documentation for more information.

The time in seconds the token will expire from the time the response was generated.

The scope value from the request.

The token type. This value will be Bearer or DPoP if a DPoP Proof was provided.