Endpoints
Overview
In support of OAuth 2.0 IETF RFC 6749, OAuth 2.0 IETF RFC 8628, JWK IETF RFC 7517, and OAuth 2.0 IETF RFC 7662, the following endpoints are provided.
In support of OpenID Connect, the following endpoints are provided:
Error responses to the OAuth endpoints are described in the following section.
Additional information about common parameters are described in this section:
If present in a query string, request parameters must be URL encoded.
Authorize
This is an implementation of the Authorization endpoint as defined by the IETF RFC 6749 Section 3.1.
Authorization Code Grant Request
To begin the Authorization Code Grant you will redirect to the Authorization endpoint from your application.
Request Parameters
The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.
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.
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
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.
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.
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.
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.
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
.
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.
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 tocode
.
In general, you only need to provide this parameter when you wish to use the form_post
response mode.
The requested response type.
For the Authorization Code Grant, this value must be set to code
.
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 anid_token
be returned in the responseoffline_access
- This scope is used to request arefresh_token
be returned in the response
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.
The unique Tenant Id used for applying the proper theme.
The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow.
Response
Response Codes
Code | Description |
---|---|
200 | The request was successful. The user is not logged in, the response will contain an HTML form to collect login credentials. |
302 | The requested user is already logged in, the request will redirect to the location specified in the redirect_uri on the request. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors or errors on the redirect URI. The error responses are covered in the OAuth Error section of the API documentation. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
The following is an example HTTP 302 redirect, line breaks added to improve readability.
Example HTTP Redirect Response
HTTP/1.1 302 Found
Location: https://piedpiper.com/callback?
code=pU2DHOWjSCVh6NJKi1ClhBYNKfuqbZVT
&locale=fr
&state=abc123
&userState=Authenticated
Redirect Parameters
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.
The state that was provided on the Authorization request. This parameter will be omitted if the state request parameter was not provided.
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.
Implicit Grant Request
To begin the Implicit Grant you will redirect to the Authorization endpoint from your application.
Request Parameters
The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.
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.
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.
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.
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.
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.
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 tocode
.
In general, you only need to provide this parameter when you wish to use the form_post
response mode.
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 anaccess_token
token id_token
- Return both theaccess_token
and theid_token
id_token
- Return anid_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.
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.
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 anid_token
be returned in the response
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.
The unique Tenant Id.
The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow.
Response
Response Codes
Code | Description |
---|---|
200 | The request was successful. The user is not logged in, the response will contain an HTML form to collect login credentials. |
302 | The requested user is already logged in, the request will redirect to the location specified in the redirect_uri on the request. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors or errors on the redirect URI. The error responses are covered in the OAuth Error section of the API documentation. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Example HTTP Redirect Response
HTTP/1.1 302 Found
Location: https://piedpiper.com/callback#
access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo
&expires_in=3599
&id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo
&locale=fr
&scope=openid
&state=abc123
&token_type=Bearer
&userState=Authenticated
Redirect Parameters
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.
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.
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.
The locale that was used 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.
The state that was provided on the Authorization request. This parameter will be omitted if the state request parameter was not provided.
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.
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.
Logout
This endpoint provides a mechanism to invalidate the user’s session held by FusionAuth, this effectively logs the user out of the FusionAuth SSO. Calling this endpoint does not revoke refresh tokens or JWTs. You can revoke the former by using the Revoke Refresh Tokens API. To revoke JWTs, implement a revocation strategy.
Since 1.10.0
The logout behavior follows that of the OpenID Connect Front-Channel Logout specification.
The Logout URL used for each application is determined using the following precedence:
- The logoutURL of the Application if defined.
- The logoutURL configured on the Tenant if defined.
/
Request
Request Parameters
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 /
.
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.
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 /
.
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.
The unique Tenant Id used for applying the proper theme.
Available since version 1.37.0
Request Body
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 /
.
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.
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 /
.
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.
The unique Tenant Id used for applying the proper theme.
Response
Response Codes
Code | Description |
---|---|
302 | The request was successful and the the redirect location will be determined by using the configuration values in the following precedence: * The post_logout_redirect_uri request parameter if present* The logoutURL defined in the Application OAuth configuration * The logoutURL defined in the Tenant OAuth configuration * / |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Token
This is an implementation of the Token endpoint as defined by the IETF RFC 6749 Section 3.2.
Complete the Authorization Code Grant Request
Authorization Code Grant : Exchange the Authorization Code for a Token
If you will be using the Authorization Code grant, you will make a request to the Token endpoint to exchange the authorization code returned from the Authorize endpoint for an access token.
Request Headers
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
.
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.
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 https://tools.ietf.org/html/rfc7636[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.
Example HTTP Request
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
Resource Owner Password Credentials Grant Request
Resource Owner Password Credentials Grant : Exchange User Credentials for a Token
If you will be using the Resource Owner Password Credential Grant, you will make a request to the Token endpoint to exchange the user’s email and password for an access token.
Request Headers
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
.
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.
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 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 anid_token
be returned in the responseoffline_access
- This scope scope is used to request arefresh_token
be returned in the response
The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow.
Example HTTP Request
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
Complete the Device Authorization Grant Request
This API has been available since 1.11.0
This is the Device Access Token Request portion of the Device Authorization Grant Specification.
Request Headers
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
.
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.
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
Example HTTP Request
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
The following response applies to the Complete the Authorization Code Grant Request , Refresh Token Grant Request and Complete the Device Authorization Grant Request examples.
Response Codes
Code | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The client could not be verified. Verify your client_id and client_secret are valid and authorized for this request. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
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
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 always be Bearer
.
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.
Example JSON Response
{
"access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in" : 3600,
"id_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"refresh_token": "ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ",
"refresh_token_id": "4c8927f1-95cd-4bf8-9534-066389ffff5e",
"scope": "openid offline_access",
"token_type" : "Bearer",
"userId" : "3b6d2f70-4821-4694-ac89-60333c9c4165"
}
Refresh Token Grant Request
If you will be using the Refresh Token Grant, you will make a request to the Token endpoint to exchange the user’s refresh token for an access token.
Request Cookies
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
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
.
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.
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 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.
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.
The end-user verification code. This code is required if using this endpoint to approve the Device Authorization.
Example HTTP Request
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
Refresh Token Grant Request
If you will be using the Refresh Token Grant, you will make a request to the Token endpoint to exchange the user’s refresh token for an access token.
Request Cookies
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
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
.
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.
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 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.
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.
The end-user verification code. This code is required if using this endpoint to approve the Device Authorization.
Example HTTP Request
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
Response Codes
Code | Description |
---|---|
200 | The request wa |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The client could not be verified. Verify your client_id and client_secret are valid and authorized for this request. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
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
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 always be Bearer
.
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.
Example JSON Response
{
"access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in" : 3600,
"id_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"token_type" : "Bearer",
"userId" : "3b6d2f70-4821-4694-ac89-60333c9c4165"
}
Client Credentials Grant Request
This feature is only available in paid plans. Please visit our pricing page to learn more.
This functionality has been available since version 1.26.
If you will be using the Client Credentials grant, you will make a request to the Token endpoint to exchange the client credentials for an access token.
Request Headers
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
.
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.
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.
Example HTTP Request
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
Response Codes
Code | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The client could not be verified. Verify your client_id and client_secret are valid and authorized for this request. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
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
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.
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"
}
Device
This endpoint been available since 1.11.0
This is an implementation of the Device Authorization endpoint as defined by the IETF RFC 8628 Section 3.1.
Device Authorize
To begin the Device Authorization Grant you will make a request to the Device Authorization endpoint from the device.
Request Headers
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.
The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.
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 anid_token
be returned in the responseoffline_access
- This scope is used to request arefresh_token
be returned in the eventual Token response.idp-link
- This scope is used to begin a linking request from a game console.
Supported console links include Epic, Nintendo, Sony Playstation Network, Steam, and Xbox.
This scope format is as follows: idp-link:{identityProviderId}:{token}
. When this scope is provided on the request, the token will be verified and when the device grant is complete, a link will be established between the FusionAuth user and the user represented by the provided token. If you need to send more than one token, separate each token using a colon character :
. Here is an example format when more than one token is required: idp-link:{identityProviderId}:{token1}:{token2}
.
Example HTTP Request
POST /oauth2/device_authorize 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&scope=offline_access
Response
Response Codes
Code | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
Response Body
The device verification code.
The number of seconds the device_code and user_code tokens returned in the response will remain active.
The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.
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.
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 .
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 .
Example JSON Response
{
"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"
}
Device User Code
This endpoint has been available since 1.46.0
This endpoint is intended to validate the end-user provided user_code and return meta-data useful when building your own interactive workflow.
This endpoint is equivalent to the Device Validate endpoint, but it will return meta-data for the user_code in a JSON body.
Request Headers
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
.
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.
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.46.0
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 end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.
Request Headers
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.
The end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.
Request Headers
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
.
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.
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.46.0
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 end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.
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 a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The provided client credentials are invalid, or the API key if provided is not valid. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
Response Body
The unique client identifier provided on the Device Authorize request.
The optional device description provided on the Device Authorize request.
The optional device name provided on the Device Authorize request.
The optional device type provided on the Device Authorize request.
The number of seconds the device_code and user_code tokens will remain active.
This is how long you have to complete the Device grant.
The human readable name of the user represented by the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The unique Identity Provider Id associated with the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The name of the Identity Provider associated with the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The type of the Identity Provider associated with the the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The unique user Id of the user represented by the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
This is the value that FusionAuth will use to uniquely link a FusionAuth User to a user in the 3rd party identity provider.
The unique Id of the Tenant.
The end-user verification code. This is the same value that was provided in the request body.
Example JSON Response
{
"client_id": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
"deviceInfo": {
"description": "Johny's Xbox"
"name": "Xbox",
"type": "Console"
},
"expires_in": 600,
"pendingIdPLink": {
"displayName": "jmoney42",
"identityProviderId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2",
"identityProviderName": "Xbox",
"identityProviderType": "Xbox",
"identityProviderUserId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2"
},
"tenantId": "5f35237d-d036-4aaa-a917-17039d4697e6",
"user_code": "FBGLLF"
}
Device Validate
This endpoint has been available since 1.11.0
This endpoint validates the end-user provided user_code from the user-interaction of the Device Authorization Grant.
If you build your own activation form you should validate the user provided code prior to beginning the Authorization grant.
If you choose to redirect to the FusionAuth provided form /oauth2/device
then it is not necessary for you to validate the user_code .
Request Parameters
The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.
The end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.
Response
Response Codes
Code | Description |
---|---|
200 | The request was successful. No response body will be returned on successful validation. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
Device Approve
This endpoint has been available since 1.46.0
Approve a user_code returned from the Device Authorize . If you are using the FusionAuth themed page for /oauth2/device
you do not need to use this because the grant will be automatically approved once the user has completed authentication and the OAuth2 Grant has completed.
If you are building your own integration to collect the user_code
from the end user, and wish to approve the Device Grant after authenticating the user, use this API to approve the device code allowing the Device Grant to complete.
Request Headers
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
.
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.
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 access token returned by this OAuth provider as the result of a successful authentication. This token must contain a sub
claim which will be used to identify the FusionAuth User.
The end-user verification code.
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 a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The client could not be verified. Verify your client_id and client_secret are valid and authorized for this request. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
Response Body
The device grant status. This will always be Approved
.
The optional device description provided on the Device Authorize request.
The optional device name provided on the Device Authorize request.
The optional device type provided on the Device Authorize request.
The human readable name of the user represented by the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The unique Identity Provider Id associated with the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The name of the Identity Provider associated with the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The type of the Identity Provider associated with the the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
The unique user Id of the user represented by the linking token provided in the idp-link:
scope value optionally provided on the Device Authorize request.
This is the value that FusionAuth will use to uniquely link a FusionAuth User to a user in the 3rd party identity provider.
The instant when the identity provider link was created.
The instant when the User logged in last using this identity provider.
The unique Id of the Tenant.
The unique Id of the User.
Example JSON Response
{
"deviceGrantStatus": "Approved",
"deviceInfo": {
"description": "Johny's Xbox"
"name": "Xbox",
"type": "Console"
},
"identityProviderLink": {
"displayName": "jmoney42",
"identityProviderId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2",
"identityProviderName": "Xbox",
"identityProviderType": "Xbox",
"identityProviderUserId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2"
},
"tenantId": "5f35237d-d036-4aaa-a917-17039d4697e6",
"userId": "3b6d2f70-4821-4694-ac89-60333c9c4165",
}
Introspect
This is an implementation of the Introspect endpoint as defined by the RFC 7662.
Request
Inspect an access token issued by this OAuth provider
Request Headers
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
.
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.
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.46.0
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 access token returned by this OAuth provider as the result of a successful authentication.
Starting in version 1.46.0
this endpoint will also accept a token generated by the Client Credentials Grant.
Example HTTP Request
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
Response Codes
Code | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The token provided in the request was not issued for the client_id provided on the request. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
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
This is an example response body when the provided access_token
was issued on behalf of a user using the Authorization Code Grant, Implicit Grant ,Password Credentials Grant or Refresh Token Grant.
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.
The unique Id of the Application for which the User has been authenticated. The presence of this claim indicates the user is registered for this application.
The client_id
that was used to request the access token.
The time of the initial authentication request, expressed as UNIX time which is the number of seconds since Epoch. This claim will remain the same even when the token has been re-issued through the use of a Refresh Token.
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.0APPLICATION_TOKEN
- The User was authenticated using an Application Authentication Token.FACEBOOK
- The User was authenticated using Facebook. available since 1.1.0FEDERATED_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.0GOOGLE
- The User was authenticated using Google. available since 1.1.0HYPR
- The User was authenticated using HYPR provider. available since 1.12.0JWT_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.0LINKEDIN
- The user was authenticated using LinkedIn. available since 1.23.0ONE_TIME_PASSWORD
The User was authenticated using a one time password. available since 1.5.0OPENID_CONNECT
- The User was authenticated using an external OpenID Connect provider. available since 1.1.0PASSWORD
- The User was authenticated using a loginId and password combination.PASSWORDLESS
- The user was authenticated using a passwordless login link. available since 1.5.0PING
- The user was authenticated using aPUT
request on the Login API. This is used to record a login event without prompting for credentials.REGISTRATION
- The user was created using the Registration API. available since 1.16.0REFRESH_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.0TWITTER
- The User was authenticated using Twitter. available since 1.1.0USER_CREATE
- The user was created using the User API. available since 1.16.0
The email address of the User.
Indicates if the User’s email has been verified.
The expiration instant of the access token, expressed as UNIX time which is the number of seconds since Epoch.
The instant the access token was issued, expressed as UNIX time which is the number of seconds since Epoch.
The issuer of the access token.
The unique identifier of the access token.
The username of the User whose claims are represented by this JWT.
The roles assigned to the User in the authenticated Application.
The scope of the access token. This will only be present if scope was requested during authentication.
The subject of the access token. This value is equal to the User’s unique Id in FusionAuth.
The FusionAuth Tenant unique Id.
Example JSON Response for a valid token
{
"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"
}
Example JSON Response for an invalid token
{
"active": false
}
Response Body
Available Since Version 1.46.0
This is an example response body when the provided access_token
was issued as the result of the Client Credentials Grant.
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.
The intended audience of this access token. This value may be a string or an array of string values representing one to many intended entities.
The expiration instant of the access token, expressed as UNIX time which is the number of seconds since Epoch.
The instant the access token was issued, expressed as UNIX time which is the number of seconds since Epoch.
The issuer of the access token.
The unique identifier of the access token.
The optional permissions requested for this access token. If no permissions were requested, this token represents all permissions allowed by the grant.
The subject of the access token. This value is equal to the Entity unique Id in FusionAuth.
The FusionAuth Tenant unique Id.
Example JSON Response for a valid token
{
"active": true,
"aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
"exp": 1487975407000,
"iat": 1487971807000,
"iss": "acme.com",
"sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}
Example JSON Response for an invalid token
{
"active": false
}
Userinfo
This is an implementation of the OpenId Connect Userinfo endpoint as defined by the OpenId Connect Section 5.3.
This endpoint may be called using the GET
or the POST
HTTP method.
Request
Returns the Claims about the authenticated End-User.
Returns the Claims about the authenticated End-User.
Request Headers
The access token issued by FusionAuth as a result of completing one of the supported authorization grants.
Example header:
Authorization: Bearer [access_token]
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 a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation. |
401 | The Authorization header containing the access token is missing or malformed. |
500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. |
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
The unique Id of the Application for which the User has been authenticated.
The birthDate of the User if available.
Format will be in YYYY-MM-DD
as defined by the OpenID Connect core specification.
The email address of the User.
Indicates if the User’s email has been verified.
The last name of the User if available.
The first name of the User if available.
The full name of the User if available.
The middle name of the User if available
The phone number of the User if available.
A URL to a picture of the User if available.
The username of the User if available.
The roles assigned to the User in the authenticated Application.
The subject of the access token. This value is equal to the User’s unique Id in FusionAuth.
Example JSON Response
{
"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"
}
JSON Web Key Set (JWKS)
Available Since Version 1.4.0
Request
Returns public keys generated by FusionAuth, used to cryptographically verify JWTs using the JSON Web Key format. You may also use the JWT Public Key API to retrieve these keys in PEM format.
You must add an asymmetric key to FusionAuth to have keys at this endpoint. A default FusionAuth installation has no public/private keypairs.
You may add keys using the admin UI by navigating to Settings -> Key Master and generating or importing them. You may also use the Keys API to generate or import keys.
Response
The response for this request should always return a 200
with a JSON body.
{
"keys": [
{
"alg": "ES384",
"crv": "P-384",
"kty": "EC",
"use": "sig",
"x": "cuu2_ua9Ma2KzV1oFO0barRxU4AlZUp0s3LVVC4REV_cZDHe7wnEE1oLCPteHMmZ",
"y": "nm2tuXEaSKNwwZWsIdu-8Ne7k7ljdhERnzcz3YzeBM5DijBvkZGpA3jlfmq5S4rS"
},
{
"alg": "RS256",
"e": "AQAB",
"kid": "0a136009-80ca-4ba3-888b-2d8efb63ff56",
"kty": "RSA",
"n": "k1S0Jj5aiQqQJcdfAcLyEdeDcIT4dD7rrYd1wU9QOwO6tlm-6GELGh5EdabubIBW_6C02ZZ8ALxgSbfrf8sDnQNmff0ncPOZ09IceCQCNiDI8TVH8nG0mD3zM_Z_wsC4tQ1Kty_vvOmFso1UM_-S473i6bV5bGSCaq_iwjX9ot-eO_3GWtdmRtPn9hY7r_b4pcU7aHH6w_3KtAx0zc-LFM08AJd2Nl8VDdNwIfifsuNpyVaEuTwFASqlTgyOfcO32QPAg85pM3boH3hOQ_U4H4daCo7u8G2BJvRLSYlhs-O4x7LjdYQAguBfwCq3fE2OcuhzW048vQZuU2vDqMSefQ",
"use": "sig"
},
{
"alg": "ES256",
"crv": "P-256",
"kid": "474f5556-9589-4970-ab13-83cd5b231850",
"kty": "EC",
"use": "sig",
"x": "XdUStYpfCtaxlya9xeRWezzRfmT9fhi5__xcnitdDcI",
"y": "VS4o2yOPhss0-JHJR4pEukoRe0H-SuFo603AFP77VMk"
},
{
"alg": "RS384",
"e": "AQAB",
"kid": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
"kty": "RSA",
"n": "nc1NzlB9OsT8CmnT9OPRQwdJlH5cyec2mCH5tL6q0MHQlokp5ERkKPAEoQOrLeXRXeRVhnuzp1TAOUsAhHKqor-JiJqTn2jeHeEmLvGonn4ik31FKP3OJ9qxsF_L3WBVmEnHMb8FoKi-1rImIzeny0R90E9MK5Mp8yvqHWSJIiOwRXzWEhXsmCHI86PA_0TyH7XsKFJjZat9wXOcueHr7C4ZS3lffaXiyYMo9fOs1vsxG8TCqdVCYVlxuZv0GrdToY3HRmif4CQ9AKXP4HU9d6p7XTRymvqlUp3iwCSCYbOlvQr-rwEe4RBf8ydPKPNUWXvpHRh1mo_hdhNusuXSJysSB02Q1stUp7Hy-aFd_3EYPI_uctluXnmlypG7HT3S-b_ZR1ha0Hwxr6ixA3hForq_HwTkX-ZIEqtufOhxU76M8p843RIRLcUZFYK_0bpOFaesph91X58DI-dPaWjlRMlvl3j-SoMtjczcjRF4TbLiCiw80JjbDfTf2MbBVBQD",
"use": "sig"
}
]
}
OpenID Configuration
The OpenID metadata describing the configuration as defined by Section 3. OpenID Provider Metadata.
Request
Returns the well known OpenID Configuration JSON document
URL segment
The tenant identifier.
Request Parameters
The tenant identifier. If provided then a specific issuer will be returned, when this property is not provided the default tenant Id will be used.
Response
The response for this request should always return a 200
with a JSON body.
{
"authorization_endpoint": "https://piedpiper.fusionauth.io/oauth2/authorize",
"backchannel_logout_supported": false,
"claims_supported": [
"applicationId",
"at_hash",
"aud",
"authenticationType",
"birthdate",
"c_hash",
"email",
"email_verified",
"exp",
"family_name",
"given_name",
"iat",
"iss",
"jti",
"middle_name",
"name",
"nbf",
"nonce",
"phone_number",
"picture",
"preferred_username",
"roles",
"sub"
],
"device_authorization_endpoint": "https://piedpiper.fusionauth.io/oauth2/device_authorize",
"end_session_endpoint": "https://piedpiper.fusionauth.io/oauth2/logout",
"frontchannel_logout_supported": true,
"grant_types_supported": [
"authorization_code",
"password",
"implicit",
"refresh_token",
"urn:ietf:params:oauth:grant-type:device_code"
],
"id_token_signing_alg_values_supported": [
"ES256",
"ES384",
"ES512",
"HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512"
],
"issuer": "piedpiper.fusionauth.io",
"jwks_uri": "https://piedpiper.fusionauth.io/.well-known/jwks.json",
"response_modes_supported": [
"form_post",
"fragment",
"query"
],
"response_types_supported": [
"code",
"id_token",
"token id_token"
],
"scopes_supported": [
"openid",
"offline_access"
],
"subject_types_supported": [
"public"
],
"token_endpoint": "https://piedpiper.fusionauth.io/oauth2/token",
"token_endpoint_auth_methods_supported": [
"client_secret_basic",
"client_secret_post",
"none"
],
"userinfo_endpoint": "https://piedpiper.fusionauth.io/oauth2/userinfo",
"userinfo_signing_alg_values_supported": [
"ES256",
"ES384",
"ES512",
"HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512"
]
}
OAuthError
Errors are either returned in a JSON response body, or as redirect parameters depending on expected response type.
JSON Response
When an error is returned from an OAuth endpoint as a JSON body the following structure can be expected in the response.
The change_password_id
field will only be present on the response if a password change is required.
Example JSON Response
{
"change_password_id": "a65f7ac3-e4ce-4bf6-bbb0-576189c4d965",
"error": "change_password_required",
"error_description": "The user is required to change their password.",
"error_reason": "change_password_breached"
}
Redirect Parameters
When an error is returned from an OAuth endpoint as a redirect, the errors are put on the redirect as query parameters.
Example HTTP Redirect
HTTP/1.1 302 Found
Location: https://piedpiper.com/callback?
error=unsupported_response_type
&error_reason=invalid_response_type
&error_description=Parameter+response_type+must+be+set+to+code+or+token.
&state=bEF7UItzlhNvE31Rf0_axShomu_vU30tMeJcqMZ9LfA0
Error Fields
Regardless of the way the error is returned to your, the field definitions are the same. Each possible value error and error_reason is documented below.
Error Parameters
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
The human-readable OAuth error description. This description should describe the error condition and it may contain a parameter value that caused the error.
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_invalid
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_id
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
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.
Client Secret
This table describes when the client_secret is required.
If required, it may be placed in either the Authorization
header or the request body.
Even when the value is not required, if it is provided in the request, it must be valid.
Previous to version 1.28.0
, whether the client secret was required was controlled by the oauthConfiguration.requireClientAuthentication value of the application object.
In that case, a value of true
is equivalent to a clientAuthenticationPolicy of Required
and a value of false
is equivalent to a clientAuthenticationPolicy of NotRequired
.
For versions 1.28.0
or later, use oauthConfiguration.clientAuthenticationPolicy to configure this functionality.
When Is the Client Secret Required
Grant | clientAuthenticationPolicy value | PKCE Used | Secret Required in Header | Secret Required in Body |
---|---|---|---|---|
Authorization Code Grant | Required | N/A | Yes | No |
Authorization Code Grant | Required | N/A | No | Yes |
Authorization Code Grant | NotRequired | N/A | No | No |
Authorization Code Grant | NotRequiredWhenUsingPKCE | Yes | No | No |
Authorization Code Grant | NotRequiredWhenUsingPKCE | No | Yes | No |
Authorization Code Grant | NotRequiredWhenUsingPKCE | No | No | Yes |
Implicit Grant | N/A | N/A | N/A | N/A |
Password Credentials Grant | Required | N/A | Yes | No |
Password Credentials Grant | Required | N/A | No | Yes |
Password Credentials Grant | NotRequired | N/A | No | No |
Refresh Token Grant | Required | N/A | Yes | No |
Refresh Token Grant | Required | N/A | No | Yes |
Refresh Token Grant | NotRequired | N/A | No | No |
Client Credentials Grant | N/A | N/A | Yes | No |
Client Credentials Grant | N/A | N/A | No | Yes |