FusionAuth Documentation

OAuth Endpoints

1. Overview

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

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

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

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

The code_challenge_method parameter as described in the Proof Key for Code Exchange by OAuth Public Clients (PKCE) specification. This parameter is required when code_challenge is set, the value must be set to S256.

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

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

 

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
           &state=abc123
           &userState=Authenticated

 

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

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

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

2.4. Response

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

 

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
           &token_type=Bearer
           &id_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo
           &scope=openid
           &state=abc123
           &userState=Authenticated

 

3. Logout

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

3.1. Request

Log the User out

URI

GET /oauth2/logout?client_id={client_id}

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

3.2. Response

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

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 7. 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 8. 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. When a code_challenge parameter has been provided on the antecedent GET /oauth2/authorize request, this parameter is then required.

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

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

The following response applies to both the Authorization Code Grant Request and the Refresh Token Grant Request examples.

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

access_token [String]

The OAuth access token as described by RFC 6749 Section 1.4

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

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

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

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

access_token [String]

The OAuth access token as described by RFC 6749 Section 1.4

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

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

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

5.1. Request

Inspect an access token issued by this OAuth provider

URI

POST /oauth2/introspect

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

5.2. Response

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

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

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
}

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

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

6.2. Response

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

7. JSON Web Key Set (JWKS)

Available Since Version 1.4.0

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

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

8. OpenID Configuration

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

8.1. Request

Returns the well known OpenID Configuration JSON document

URI

GET /.well-known/openid-configuration

8.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",
  "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"
  ],
  "grant_types_supported": [
    "authorization_code",
    "password",
    "implicit",
    "refresh_token"
  ],
  "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_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"
  ]
}