OAuth Endpoints

Request Parameters

client_id [String] Required

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

code_challenge [String] Optional Available since 1.8.0

The code_challenge parameter as described in the Proof Key for Code Exchange by OAuth Public Clients (PKCE) specification. When this parameter is provided during the Authorization request, a corresponding code_verifier parameter is required on the subsequent POST to the /oauth2/token endpoint.

code_challenge_method [String] Optional Available since 1.8.0 default is S256

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

The possible values are:

• S256 - SHA-256

idp_hint [UUID] Optional Available since 1.19.0

An optional unique Identity Provider Id that can allow you to bypass the FusionAuth login page.

Adding this request parameter will cause the FusionAuth login page to be skipped, and instead a 302 will be returned with a Location header of the IdP login URL. The end result is functionally equivalent to the end user clicking on the "Login with Pied Piper" button, or entering their email address when using the IdP configuration with managed domains.

locale [String] Optional

The locale to be used to render the login page. This is useful if you already know the user’s preferred locale before redirecting the user to FusionAuth. See the Theme Localization documentation for more information.

login_hint [String] Optional Available since 1.19.0

An optional email address or top level domain that can allow you to bypass the FusionAuth login page when using managed domains.

If using managed domains, adding this request parameter will cause the FusionAuth login page to be skipped, and instead a 302 will be returned with a Location header of the IdP login URL. The end result is functionally equivalent to the end entering their email address when using the IdP configuration with managed domains.

If not using managed domains, providing an email address using this parameter prepopulates the email address in the login page.

metaData.device.description [String] Optional

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.

nonce [String] Optional Available since 1.5.0

The nonce parameter as described in the OpenID Connect core specification. When this parameter is provided during the Authorization request, the value will be returned in the id_token.

redirect_uri [String] Required

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.

response_mode [String] Optional Available since 1.11.0

Determines how the result parameters are to be returned to the caller. When this parameter is not provided the default response mode will be used based upon the response_type field.

The default when the response_type is set to code is query, the default when the response_type is set to token, token id_token or id_token is fragment.

The possible values are:

• form_post

• fragment

• query - This response mode can only be used when the response_type is set to code.

  In general, you only need to provide this parameter when you wish to use the form_post response mode.

response_type [String] Required

The requested response type. For the Authorization Code Grant, this value must be set to code.

scope [String] Optional

If you are using OpenID Connect, the request must contain this parameter and at minimum it must contain openid. This parameter may contain multiple scopes space separated. 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 is used to request a refresh_token be returned in the response

state [String] Optional

The optional state parameter. This is generally used as a Cross Site Request Forgery (CSRF) token or to provide deeplinking support. Any value provided in this field will be returned on a successful redirect. See OpenID Connect core specification for additional information on how this parameter may be utilized.

tenantId [UUID] Required Available since 1.8.0

The unique Tenant Id used for applying the proper theme.

user_code [String] Optional Available since 1.11.0

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

Redirect Parameters

code [String]

The authorization code.

locale [String]

The locale that was to render the login page, or a previously selected locale by the user during a previous session. This may be useful to know in your own application so you can continue to localize the interface for the language the user selected while on the FusionAuth login page. See the Theme Localization documentation for more information.

state [String]

The state that was provided on the Authorization request. This parameter will be omitted if the state parameter was not provided on the initial authentication request.

userState [String]

The FusionAuth user state.

The possible values are:

• Authenticated - The user is successfully authenticated for the requested application.

• AuthenticatedNotRegistered - The user is successfully authenticated, but not registered for the requested application.

Request Parameters

client_id [String] Required

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

idp_hint [UUID] Optional Available since 1.19.0

An optional unique Identity Provider Id that can allow you to bypass the FusionAuth login page.

Adding this request parameter will cause the FusionAuth login page to be skipped, and instead a 302 will be returned with a Location header of the IdP login URL. The end result is functionally equivalent to the end user clicking on the "Login with Pied Piper" button, or entering their email address when using the IdP configuration with managed domains.

locale [String]

The locale to be used to render the login page. This is useful if you already know the user’s preferred locale before redirecting the user to FusionAuth. See the Theme Localization documentation for more information.

login_hint [String] Optional Available since 1.19.0

An optional email address or top level domain that can allow you to bypass the FusionAuth login page when using managed domains.

If using managed domains, adding this request parameter will cause the FusionAuth login page to be skipped, and instead a 302 will be returned with a Location header of the IdP login URL. The end result is functionally equivalent to the end entering their email address when using the IdP configuration with managed domains.

If not using managed domains, providing an email address using this parameter prepopulates the email address in the login page.

nonce [String] Optional Available since 1.5.0

The nonce parameter as described in the OpenID Connect core specification. When this parameter is provided during the Authorization request, the value will be returned in the id_token if requested by the response_type parameter.

redirect_uri [String] Required

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.

response_mode [String] Optional Available since 1.11.0

Determines how the result parameters are to be returned to the caller. When this parameter is not provided the default response mode will be used based upon the response_type field.

The default when the response_type is set to code is query, the default when the response_type is set to token, token id_token or id_token is fragment.

The possible values are:

• form_post

• fragment

• query - This response mode can only be used when the response_type is set to code.

  In general, you only need to provide this parameter when you wish to use the form_post response mode.

response_type [String] Required

The requested response type, this value determines which tokens will be returned in the redirect URL.

For the Implicit Grant, this value must be set to one of the following values:

• token - Return an access_token

• token id_token - Return both the access_token and the id_token

• id_token - Return an id_token

  The token response type is not supported when using OpenID Connect. This means that if you specify the openid scope the token response type is not allowed.

nonce [String] Optional Available since 1.5.0

The nonce parameter as described in the OpenID Connect core specification. When this parameter is provided during the Authorization request, the value will be returned in the id_token if requested by the response_type parameter.

scope [String] Optional

If you are using OpenID Connect, the request must contain this parameter and at minimum it must contain openid.

Available scopes:

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

state [String] Optional

The optional state parameter. This is generally used as a Cross Site Request Forgery (CSRF) token or to provide deeplinking support. Any value provided in this field will be returned on a successful redirect. See OpenID Connect core specification for additional information on how this parameter may be utilized.

tenantId [UUID] Required Available since 1.8.0

The unique Tenant Id.

user_code [String] Optional Available since 1.11.0

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

Redirect Parameters

access_token [String]

The OAuth access token as described by RFC 6749 Section 1.4. This request parameter will be omitted if an access token was not requested in the response_type request parameter. See the OAuth Tokens documentation for more information.

expires_in [String]

The number of seconds the access token will remain active. This request parameter will be omitted if an access token was not requested in the response_type request parameter.

id_token [String]

The OpenID Id Token. This token is represented as a JSON Web Token (JWT). This request parameter will be omitted if an id token was not requested in the response_type request parameter. See the OAuth Tokens documentation for more information.

locale [String]

The locale that was to render the login page, or a previously selected locale by the user during a previous session. This may be useful to know in your own application so you can continue to localize the interface for the language the user selected while on the FusionAuth login page. See the Theme Localization documentation for more information.

state [String]

The state that was provided on the Authorization request. This parameter will be omitted if the state request parameter was not provided.

token_type [String]

The token type. The value will be Bearer if an access token was requested in the response_type request parameter, this request parameter will otherwise be omitted.

userState [String]

The FusionAuth user state.

The possible values are:

• Authenticated - The user is successfully authenticated for the requested application.

• AuthenticatedNotRegistered - The user is successfully authenticated, but not registered for the requested application.

Request Parameters

client_id [String] Optional

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are requesting to logout, this value is used to identify the correct redirect URI.

Generally speaking this parameter is required, if you are using the id_token_hint, this parameter becomes redundant because the application can be identified based upon the id_token.

If you do not provide the id_token_hint and you also omit this parameter, the request will not fail, but the logout URL defined in the Tenant configuration will be utilized. If the Tenant logout URL is not defined, the request will result in a redirect to the current base URL at the root path of /.

id_token_hint [String] Optional Available since 1.10.0

The id_token_hint parameter as described in the OpenID Connect Session Management specification.

This is the previously issued id_token passed to the logout endpoint as a hint about the End-User’s current authenticated session with the Client.

This parameter is only used if client_id is not provided.

Note that prior to version 1.37.0 this parameter would only work if it was not expired. This was corrected in version 1.37.0 and as long as the token is signed by FusionAuth, even if expired, the token can be used to identify the user and application during the logout request.

post_logout_redirect_uri [String] Optional Available since 1.10.0

The URI to redirect to upon a successful logout. This URI must have been configured previously in the FusionAuth Application OAuth configuration as an Authorized Redirect URL. See the Core Concepts OAuth section for additional information on configuring redirect URIs.

If this parameter is omitted, the logout URL defined in the Application OAuth configuration will be utilized. If an Application OAuth logout URL is not defined, the logout URL defined in the Tenant configuration will be utilized. If the Tenant logout URL is not defined, the request will result in a redirect to the current base URL at the root path of /.

state [String] Optional Available since 1.10.0

The state parameter as described in the OpenID Connect Session Management specification. This is an opaque value used to maintain state between the logout request and the callback.

tenantId [UUID] Required Available since 1.8.0

The unique Tenant Id used for applying the proper theme.

Log the User out of the FusionAuth SSO session using an HTTP POST request.

Request Body

client_id [String] Optional

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are requesting to logout, this value is used to identify the correct redirect URI.

Generally speaking this parameter is required, if you are using the id_token_hint, this parameter becomes redundant because the application can be identified based upon the id_token.

If you do not provide the id_token_hint and you also omit this parameter, the request will not fail, but the logout URL defined in the Tenant configuration will be utilized. If the Tenant logout URL is not defined, the request will result in a redirect to the current base URL at the root path of /.

id_token_hint [String] Optional

The id_token_hint parameter as described in the OpenID Connect Session Management specification.

This is the previously issued id_token passed to the logout endpoint as a hint about the End-User’s current authenticated session with the Client.

This parameter is only used if client_id is not provided.

Note that prior to version 1.37.0 this parameter would only work if it was not expired. This was corrected in version 1.37.0 and as long as the token is signed by FusionAuth, even if expired, the token can be used to identify the user and application during the logout request.

post_logout_redirect_uri [String] Optional

The URI to redirect to upon a successful logout. This URI must have been configured previously in the FusionAuth Application OAuth configuration as an Authorized Redirect URL. See the Core Concepts OAuth section for additional information on configuring redirect URIs.

If this parameter is omitted, the logout URL defined in the Application OAuth configuration will be utilized. If an Application OAuth logout URL is not defined, the logout URL defined in the Tenant configuration will be utilized. If the Tenant logout URL is not defined, the request will result in a redirect to the current base URL at the root path of /.

state [String] Optional

The state parameter as described in the OpenID Connect Session Management specification. This is an opaque value used to maintain state between the logout request and the callback.

tenantId [UUID] Required

The unique Tenant Id used for applying the proper theme.

Request Headers

Authorization [String] Optional Available since 1.3.0

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.

Request Headers

Content-Type [String] Required

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

Request Body

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id [String] Optional

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.

client_secret [String] Optional Available since 1.5.0

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

code [String] Required

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

code_verifier [String] Optional Available since 1.8.0

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.

grant_type [String] Required

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

redirect_uri [String] Required

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.

POST /oauth2/token HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&code=+WYT3XemV4f81ghHi4V+RyNwvATDaD4FIj0BpfFC4Wzg&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.piedpiper.com%2Flogin

Request Headers

Authorization [String] Optional Available since 1.3.0

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.

Request Headers

Content-Type [String] Required

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

Request Body

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id [String] Optional

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.

client_secret [String] Optional Available since 1.5.0

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

grant_type [String] Required

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

metaData.device.description [String] Optional Available since 1.20.1

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

metaData.device.name [String] Optional Available since 1.20.1

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

metaData.device.type [String] Optional Available since 1.20.1

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

• BROWSER

• DESKTOP

• LAPTOP

• MOBILE

• OTHER

• SERVER

• TABLET

• TV

• UNKNOWN

username [String] Required

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

password [String] Required

The user’s password.

scope [String] Optional

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

Available grant types:

• 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

user_code [String] Optional Available since 1.11.0

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

POST /oauth2/token HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&grant_type=password&loginId=bishop%piedpiper.com&password=Setec+Astronomy

Request Headers

Authorization [String] Optional Available since 1.3.0

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.

Request Headers

Content-Type [String] Required

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

Request Body

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id [String] Optional

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.

client_secret [String] Optional

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

device_code [String] Required

grant_type [String] Required

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

POST /oauth2/token HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 166
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Response Body

access_token [String]

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

expires_in [Integer]

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

id_token [String]

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.

refresh_token [String]

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. See oauthConfiguration.generateRefreshTokens in the Application API or the Generate refresh tokens toggle in the FusionAuth UI when editing an application.

token_type [String]

The token type as defined by RFC 6749 Section 7.1. This value will always be Bearer.

userId [String]

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.

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "expires_in" : 3600,
  "id_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "refresh_token": "ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ",
  "token_type" : "Bearer",
  "userId" : "3b6d2f70-4821-4694-ac89-60333c9c4165"
}

Request Headers

Authorization [String] Optional Available since 1.3.0

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.

Request Cookies

access_token [String] Optional Available since 1.16.0

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 parameter are provided, the cookie will take precedence.

Request Headers

Content-Type [String] Required

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

Request Parameters

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

access_token [String] Optional Available since 1.16.0

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.

client_id [String] Optional

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.

client_secret [String] Optional Available since 1.5.0

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

grant_type [String] Required

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

refresh_token [String] Required

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

scope [String] Optional

This parameter is optional and if omitted, the same scope requested during the authorization request will be used. If provided the scopes must match those requested during the initial authorization request.

user_code [String] Optional Available since 1.11.0

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

POST /oauth2/token HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Cookie: access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFuYV91STRWbWxiMU5YVXZ0cV83SjZKZFNtTSJ9.eyJleHAiOjE1ODgzNTM0NjAsImlhdCI6MTU4ODM1MzQwMCwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.ZoIHTo3Pv0DpcELeX_wu-ZB_rd988jefZc2Ozu9_p59kttwqMm5PV8IDbgxJw9xcq9TFoNG8e_B6renoc11JC54UbiyeXBjF7EH01n9LDz-zTGqu9U72470Z4E7IPAHcyvJIBx4Mp9sgsEYAUm9Tb8ChudqNHhn6ZnXYI7Sew7CtGlu62f10wdBYGX0soYARHBv9CwhJC3-gsD2HLmqHAP_XhrpaYPNr5EAvmCHlM-JlTiEQ9bXwSc4gv-XbPQWamwy8Kcdb-g0EEAml_dC_b2CduwwYg0EoPQB3tQxzTUQzADi7K6q0CtQXv2_1VrRi6aQ4lt7v7t-Na39wGry_pA
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&grant_type=refresh_token&refresh_token=ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ

Response Body

access_token [String]

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

expires_in [Integer]

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

id_token [String]

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.

token_type [String]

The token type as defined by RFC 6749 Section 7.1. This value will always be Bearer.

userId [String]

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.

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "expires_in" : 3600,
  "id_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "token_type" : "Bearer",
  "userId" : "3b6d2f70-4821-4694-ac89-60333c9c4165"
}

Request Headers

Content-Type [String] Required

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

Request Headers

Authorization [String] Optional Available since 1.3.0

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.

Request Parameters

Ensure you are sending these parameters as form encoded data in the request body. Do not send these parameters in a query string or as JSON.

client_id [String] Optional

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.

client_secret [String] Optional

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.

grant_type [String] Required

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

scope [String] Optional

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.

POST /oauth2/token HTTP/1.1
Host: piedpiper.fusionauth.io
Authorization: Basic MDkyZGJkZWQtMzBhZi00MTQ5LTljNjEtYjU3OGYyYzcyZjU5OitmY1hldDlJdTJrUWk2MXlXRDlUdTRSZVoxMTNQNnlFQWtyMzJ2NldLT1E9
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436

grant_type=client_credentials
    &scope=target-entity%3Ae13365f1-a270-493e-bd1b-3d239d753d53%3Aread

Response Body

access_token [String]

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

expires_in [Integer]

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

scope [String]

The scope value from the request.

token_type [String]

The token type. The value will be Bearer.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjM0ZjE3ZDdiNzIifQ.eyJhdWQiOiJlMTMzNjVmMS1hMjcwLTQ5M2UtYmQxYi0zZDIzOWQ3NTNkNTMiLCJleHAiOjE2MjAyMzc3MjksImlhdCI6MTYyMDIzNDEyOSwiaXNzIjoiaHR0cHM6Ly9sb2NhbC5mdXNpb25hdXRoLmlvIiwic3ViIjoiMjkzNGY0MWYtZDI3Ny00YTMyLWIwZDUtMTZlNDdkYWQ5NzIxIiwianRpIjoiMGIwMmY1MDktYmNmMy00YjhkLWEzZGItMDNmOThhY2U5ZDlmIiwicGVybWlzc2lvbnMiOnsiZTEzMzY1ZjEtYTI3MC00OTNlLWJkMWItM2QyMzlkNzUzZDUzIjpbInJlYWQiXX19.1BR367JxpWp33HuHEY0_zHuVDmnYrgi7CzzjlIYwtqQ",
  "expires_in": 3599,
  "scope":"target-entity:e13365f1-a270-493e-bd1b-3d239d753d53:read",
  "token_type":"Bearer"
}

Response Body

device_code [String]

The device verification code.

expires_in [Integer]

The number of seconds the device_code and user_code tokens returned in the response will remain active.

interval [Integer]

The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.

user_code [String]

The end-user verification code. This value will generally be displayed on the device for the user to read and enter into an activation form.

verification_uri [String]

The end-user verification URI on the authorization server. This value will generally be displayed on the device to instruct the user where to navigate in order to find the form where they may enter the provided user_code.

verification_uri_complete [String]

A verification URI that includes the user_code. This is the same value as returned in the verification_uri with the user_code appended as a request parameter. This can be used to build a QR code or provide a clickable link that may pre-populate a form with the user_code.

{
  "device_code": "e6f_lF1rG_yroI0DxeQB5OrLDKU18lrDhFXeQqIKAjg",
  "expires_in": 600,
  "interval": 5,
  "user_code": "FBGLLF",
  "verification_uri": "https://piedpiper.com/device",
  "verification_uri_complete": "https://piedpiper.com/device?user_code=FBGLLF"
}

Request Headers

Content-Type [String] Required

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

Request Parameters

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id [String] Required

The unique client identifier. The client Id is the Id of the FusionAuth Application for which this token was generated.

token [String] Required

The access token returned by this OAuth provider as the result of a successful authentication.

POST /oauth2/introspect HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MTM3MTM3NzIsImlhdCI6MTUxMzcxMDE3MiwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI3MWMxZjE5Yy1kZTRlLTRiZDEtODc3My0zNThkYmIwNWYxNWEiLCJlbWFpbCI6ImRhbmllbEBpbnZlcnNvZnQuY29tIiwiYXBwbGljYXRpb 25JZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwicm9sZXMiOltdfQ.KxfM37hlw-5mKXOP9bCm7O6qdQdleT4gJmudhFueiJA

Response Body

active [String]

When this value is true the token is valid and additional claims will be provided in the response body. When this value is false no claims will be provided in the response body.

applicationId [UUID]

The unique Id of the Application for which the User has been authenticated.

aud [String]

The client_id that was used to request the access token.

authenticationType [String]

The method used to authenticate the User which resulted in this JWT being generated. The possible values are:

• APPLE - The User was authenticated using Apple. Available since 1.17.0

• APPLICATION_TOKEN - The User was authenticated using an Application Authentication Token.

• FACEBOOK - The User was authenticated using Facebook.   Available since 1.1.0

• FEDERATED_JWT - The User was authenticated using a JWT from an external Identity Provider.

• GENERIC_CONNECTOR - The user was authenticated using a generic connector.   Available since 1.18.0

• GOOGLE - The User was authenticated using Google. Available since 1.1.0

• HYPR - The User was authenticated using HYPR provider. Available since 1.12.0

• JWT_SSO - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application.

• LDAP_CONNECTOR - The user was authenticated using an LDAP connector.   Available since 1.18.0

• LINKEDIN - The user was authenticated using LinkedIn.   Available since 1.23.0

• ONE_TIME_PASSWORD The User was authenticated using a one time password.   Available since 1.5.0

• OPENID_CONNECT - The User was authenticated using an external OpenID Connect provider. Available since 1.1.0

• PASSWORD - The User was authenticated using a loginId and password combination.

• PASSWORDLESS - The user was authenticated using a passwordless login link.   Available since 1.5.0

• PING - The user was authenticated using the PING API w/ a valid JWT.

• REGISTRATION - The user was created using the Registration API.   Available since 1.16.0

• REFRESH_TOKEN - The User requested a new JWT using a Refresh Token.

• SAMLv2 - The User was authenticated using an external SAMLv2 provider. Available since 1.6.0

• TWITTER - The User was authenticated using Twitter. Available since 1.1.0

• USER_CREATE - The user was created using the User API.   Available since 1.16.0

email [String]

The email address of the User.

email_verified [Boolean]

Indicates if the User’s email has been verified.

exp [Long]

The expiration instant of the access token, expressed as UNIX time which is the number of seconds since Epoch.

iat [Long]

The instant the access token was issued, expressed as UNIX time which is the number of seconds since Epoch.

iss [String]

The issuer of the access token.

preferred_username [String] Available since 1.5.0

The username of the User whose claims are represented by this JWT.

roles [Array<String>]

The roles assigned to the User in the authenticated Application.

sub [UUID]

The subject of the access token. This value is equal to the User’s unique Id in FusionAuth.

{
  "active": true,
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "authenticationType": "PASSWORD",
  "email": "test0@fusionauth.io",
  "email_verified": true,
  "exp": 1487975407000,
  "iat": 1487971807000,
  "iss": "acme.com",
  "roles": [
    "admin"
  ],
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}

{
  "active": false
}

Request Headers

Authorization [String] Required

The access token issued by FusionAuth as a result of completing one of the supported authorization grants.

Example header:

Response Body

applicationId [UUID]

The unique Id of the Application for which the User has been authenticated.

birthdate [String] Available since 1.1.0

The birthDate of the User if available. Format will be in YYYY-MM-DD as defined by the OpenID Connect core specification.

email [String]

The email address of the User.

email_verified [Boolean]

Indicates if the User’s email has been verified.

family_name [String] Available since 1.1.0

The last name of the User if available.

given_name [String] Available since 1.1.0

The first name of the User if available.

name [String] Available since 1.1.0

The full name of the User if available.

middle_name [String] Available since 1.1.0

The middle name of the User if available.

phone_number [String] Available since 1.1.0

The phone number of the User if available.

picture [String] Available since 1.1.0

A URL to a picture of the User if available.

preferred_username [String] Available since 1.1.0

The username of the User if available.

roles [Array]

The roles assigned to the User in the authenticated Application.

sub [UUID]

The subject of the access token. This value is equal to the User’s unique Id in FusionAuth.

{
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "birthdate": "1982-03-10",
  "email": "richard@pipedpuper.com",
  "email_verified": true,
  "family_name": "Hendricks",
  "given_name": "Richard",
  "phone_number": "555-555-5555",
  "picture": "http://www.piedpiper.com/app/themes/pied-piper/dist/images/photo-richard.png",
  "roles": [
    "admin"
  ],
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}

Request Parameters

tenantId [UUID] Optional Available since 1.8.0

The tenant identifier. If provided then a specific issuer will be returned.

Error Parameters

error [String]

The OAuth error response type. In most cases these values are defined or suggested by an RFC or other specification.

The possible values are:

• authorization_pending

• change_password_required

• expired_token

• invalid_grant

• invalid_request

• invalid_scope

• invalid_token

• server_error

• two_factor_required

• unauthorized_client

• unsupported_grant_type

• unsupported_response_type

error_description [String]

The human-readable OAuth error description. This description should describe the error condition and it may contain a parameter value that caused the error.

error_reason [String]

The OAuth error reason. These reason codes are defined by FusionAuth to provide you a specific reason code so that you may identify the specific reason the request failed. The defined error codes as defined by OAuth2 or OpenID Connect only provide general indications such as an invalid request that may be caused by more than one parameter. Each of the values returned in this field will represent a specific error.

The possible values are:

• access_token_expired

• access_token_failed_processing

• access_token_malformed

• access_token_unavailable_for_processing

• auth_code_not_found

• change_password_administrative

• change_password_breached

• change_password_expired

• change_password_validation

• client_authentication_missing

• client_id_mismatch

• grant_type_disabled

• invalid_additional_client_id

• invalid_client_authentication_scheme

• invalid_client_authentication

• invalid_client_id

• invalid_device_code

• invalid_grant_type

• invalid_id_token_hint

• invalid_origin

• invalid_pkce_code_challenge_method

• invalid_pkce_code_challenge

• invalid_pkce_code_verifier

• invalid_post_logout_redirect_uri

• invalid_redirect_uri

• invalid_response_mode

• invalid_response_type

• invalid_user_code

• invalid_user_credentials

• login_prevented

• missing_client_id

• missing_code

• missing_code_challenge,

• missing_code_verifier,

• missing_device_code

• missing_grant_type

• missing_redirect_uri

• missing_refresh_token

• missing_response_type

• missing_token

• missing_user_code

• missing_verification_uri

• refresh_token_not_found

• unknown

• user_code_expired

• user_expired

• user_locked

• user_not_found

state [String]

The state that was provided on the Authorization request. This parameter is only returned during an HTTP redirect if it was provided on the initial request.