OAuth Endpoints - FusionAuth

1. Overview

In support of OAuth 2.0 IETF RFC 6749 and OAuth 2.0 IETF RFC 8628 the following endpoints are provided.

Authorize
- Authorization Code Grant Request
- Implicit Grant Request
Logout
Token
Device
Device Validate
Introspect

In support of OpenID Connect, the following endpoints are provided:

Userinfo
JSON Web Key Set (JWKS)
OpenID Configuration

Error responses to the OAuth endpoints are described in the following section.

OAuthError

2. Authorize

This is an implementation of the Authorization endpoint as defined by the IETF RFC 6749 Section 3.1.

2.1. Authorization Code Grant Request

To begin the Authorization Code Grant you will redirect to the Authorization endpoint from your application.

URI

GET /oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&tenantId={tenantId}

Table 1. 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
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.
metaData.device.description [String] Optional	A human readable description of the device used during login. This meta data 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. 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.

2.2. Response

Table 2. Response Codes
Code	Description
200	The request was successful. The user is not logged in, the response will contain and 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 OAuthError 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

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

2.3. Implicit Grant Request

To begin the Implicit Grant you will redirect to the Authorization endpoint from your application.

URI

GET /oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=token%20id_token&tenantId={tenantId}

Table 4. Request Parameters
client_id [String] Required	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you you are attempting to authenticate.
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.
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. 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.

2.4. Response

Table 5. Response Codes
Code	Description
200	The request was successful. The user is not logged in, the response will contain and 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. The redirect from an Implicit Grant will contain parameters after the fragment #.

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

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

3. Logout

This endpoint provides a mechanism to invalidate the user’s session held by FusionAuth, this effectively logs the user out of FusionAuth.

Since 1.10.0 The logout behavior follows that of the OpenID Connect Front-Channel Logout specification. Additionally, the logoutUrl used for each application is determined as follows: The logoutUrl of the Application is used, if that isn’t set then the logoutUrl of the Tenant is used.

3.1. Request

Log the User out

URI

GET /oauth2/logout?client_id={client_id}&tenantId={tenantId}

Table 7. Request Parameters
client_id [String] Optional	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you you are requesting to logout, this value is used to identify the correct redirect URI. If the `client_id` is not provided the Logout URL defined in the Global OAuth Configuration will be used.
id_token_hint [String] Optional Available Since 1.10.0	The `id_token_hint` parameter as described in the OpenID Connect Session Management specification. Previously issued ID Token passed to the logout endpoint as a hint about the End-User’s current authenticated session with the Client. Only used if `client_id` is not provided.
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. See Applications in the FusionAuth User Guide for additional information on configuring the redirect URI.
state [String] Optional Available Since 1.10.0	The `state` parameter as described in the OpenID Connect Session Management specification. 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.

3.2. Response

Table 8. 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 logout URL defined in the Application OAuth configuration The logout URL defined in the FusionAuth System OAuth configuration The root context / (slash)
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.

4. Token

This is an implementation of the Token endpoint as defined by the IETF RFC 6749 Section 3.2.

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

URI

POST /oauth2/token

Table 9. Request Headers
Authorization [String] Optional Available Since 1.3.0	If you have enabled `requireClientAuthentication` on the Application the user logged into, than you must provide client authentication using the Basic Authentication Scheme authorization header. The header 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: Concatenation Example `463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. Here is what the resulting Authorization header looks like: Basic Authorization Header Example `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`

Table 10. Request Parameters
client_id [String] Optional	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you 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 value may optionally be provided in the request body instead of the `Authorization` header documented above.
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 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.

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

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

URI

POST /oauth2/token

Table 11. Request Headers
Authorization [String] Optional Available Since 1.3.0	If you have enabled `requireClientAuthentication` on the Application the user logged into, than you must provide client authentication using the Basic Authentication Scheme authorization header. The header 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: Concatenation Example `463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. Here is what the resulting Authorization header looks like: Basic Authorization Header Example `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`

Table 12. Request Parameters
client_id [String] Optional	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you 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 value may optionally be provided in the request body instead of the `Authorization` header documented above.
grant_type [String] Required	The grant type to be used. This value must be set to `password`
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.

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

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

URI

POST /oauth2/token

Table 13. Request Headers
Authorization [String] Optional Available Since 1.3.0	If you have enabled `requireClientAuthentication` on the Application the user logged into, than you must provide client authentication using the Basic Authentication Scheme authorization header. The header 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: Concatenation Example `463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. Here is what the resulting Authorization header looks like: Basic Authorization Header Example `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`

Table 14. Request Parameters
client_id [String] Optional	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you 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 value may optionally be provided in the request body instead of the `Authorization` header documented above.
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`

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

4.4. Response

The following response applies to the Complete the Authorization Code Grant Request, Refresh Token Grant Request and the Complete the Device Authorization Grant Request examples.

Table 15. 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.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 16. Response Body
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.

Example JSON Response

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

4.5. Refresh Token Grant Request

Refresh Token Grant : Exchange a Refresh Token for an Access Token

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.

URI

POST /oauth2/token

Table 17. Request Headers
Authorization [String] Optional Available Since 1.3.0	If you have enabled `requireClientAuthentication` on the Application the user logged into, than you must provide client authentication using the Basic Authentication Scheme authorization header. The header 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: Concatenation Example `463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. Here is what the resulting Authorization header looks like: Basic Authorization Header Example `Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l`

Table 18. Request Parameters
client_id [String] Optional	The unique client identifier. The client Id is the Id of the FusionAuth Application in which you 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 value may optionally be provided in the request body instead of the `Authorization` header documented above.
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.

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=refresh_token&refresh_token=ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ

4.6. Response

Table 19. 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.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 20. Response Body
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.

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

5. 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. To begin the Device Authorization Grant you will make a request to the Device Authorization endpoint from the device.

URI

POST /oauth2/device_authorize

Table 21. 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.
scope [String] Optional	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 eventual Token response.

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

5.1. Response

Table 22. 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 OAuthError 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.

Table 23. 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 as 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"
}

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

URI

GET /oauth2/device/validate?client_id={client_id}&user_code={user_code}

Table 24. 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.
user_code [String] Required	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.

6.1. Response

Table 25. 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 OAuthError 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.

7. Introspect

This is an implementation of the Introspect endpoint as defined by the RFC 7662.

7.1. Request

Inspect an access token issued by this OAuth provider

URI

POST /oauth2/introspect

Table 26. Request Parameters
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.

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

7.2. Response

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

Table 28. 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: `APPLICATION_TOKEN` - The User was authenticated using an Application Authentication Token. `FEDERATED_JWT` - The User was authenticated using a JWT from an external Identity Provider. `JWT_SSO` - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application. `ONE_TIME_PASSWORD` The User was authenticated using a one time password. Available Since 1.5.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 `REFRESH_TOKEN` - The User requested a new JWT using a Refresh Token. `FACEBOOK` - The User was authenticated using Facebook. Available Since 1.1.0 `GOOGLE` - The User was authenticated using Google. Available Since 1.1.0 `TWITTER` - The User was authenticated using Twitter. Available Since 1.1.0 `OPENID_CONNECT` - The User was authenticated using an external OpenID Connect provider. Available Since 1.1.0 `SAMLv2` - The User was authenticated using an external SAMLv2 provider. Available Since 1.6.0 `HYPR` - The User was authenticated using HYPR provider. Available Since 1.12.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 that 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 who 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.

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
}

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

8.1. Request

Returns the Claims about the authenticated End-User.

URI

GET /oauth2/userinfo

Returns the Claims about the authenticated End-User.

URI

POST /oauth2/userinfo

Table 29. Request Headers
Authorization [String] Required	The access token issued by FusionAuth as a result of completing one of the supported authorization grants. Example header: `Authorization: Bearer <access_token>`

8.2. Response

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

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

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

9. JSON Web Key Set (JWKS)

Available Since Version 1.4.0

9.1. Request

Returns public keys used by FusionAuth 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.

URI

GET /.well-known/jwks.json

9.2. Response

The response for this request should always return a 200 with a JSON body.

Example JSON Response

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

10. OpenID Configuration

The OpenID metadata describing the configuration as defined by Section 3. OpenID Provider Metadata.

10.1. Request

Returns the well known OpenID Configuration JSON document

URI

GET /.well-known/openid-configuration

Table 32. Request Parameters
tenantId [UUID] Optional Available Since 1.8.0	The tenant identifier. If provided then a specific issuer will be returned.

10.2. Response

The response for this request should always return a 200 with a JSON body.

Example JSON Response

{
  "authorization_endpoint": "https://piedpiper.fusionauth.io/oauth2/authorize",
  "backchannel_logout_supported": false,
  "claims_supported": [
    "applicationId",
    "aud",
    "authenticationType",
    "birthdate",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "middle_name",
    "nbf",
    "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"
  ]
}

11. OAuthError

Errors are either returned in a JSON response body, or as redirect parameters depending on expected response type.

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

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

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

Table 33. Error Parameters
error [String]	The OAuth error response type. In most cases these values are defined or suggested by an 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 indicates 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_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.