FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

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

    • Authorize

      • Authorization Code Grant Request

      • Implicit Grant Request

    • Logout

    • Token

      • Complete the Authorization Code Grant Request

      • Resource Owner Password Credentials Grant Request

      • Complete the Device Authorization Grant Request

      • Refresh Token Grant Request

      • Client Credentials Grant Request

    • 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

    Additional information about common parameters are described in this section:

    • Client Secret

    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.

    URI

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

    Request Parameters

    client_id [String] Required

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

    code_challenge [String] Optional Available since 1.8.0

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

    code_challenge_method [String] Optional Available since 1.8.0 default is S256

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

    The possible values are:

    • S256 - SHA-256

    idp_hint [UUID] Optional Available since 1.19.0

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

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

    locale [String] Optional

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

    login_hint [String] Optional Available since 1.19.0

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

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

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

    metaData.device.description [String] Optional

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

    nonce [String] Optional Available since 1.5.0

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

    redirect_uri [String] Required

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

    response_mode [String] Optional Available since 1.11.0

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

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

    The possible values are:

    • form_post

    • fragment

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

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

    response_type [String] Required

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

    scope [String] Optional

    If you are using OpenID Connect, the request must contain this parameter and at minimum it must contain openid. This parameter may contain multiple scopes space separated. For example, the value of openid offline_access provides two scopes on the request.

    Available scopes:

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

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

    state [String] Optional

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

    tenantId [UUID] Required Available since 1.8.0

    The unique Tenant Id used for applying the proper theme.

    user_code [String] Optional Available since 1.11.0

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

    Response

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

    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.

    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}

    Request Parameters

    client_id [String] Required

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

    idp_hint [UUID] Optional Available since 1.19.0

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

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

    locale [String]

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

    login_hint [String] Optional Available since 1.19.0

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

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

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

    nonce [String] Optional Available since 1.5.0

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

    redirect_uri [String] Required

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

    response_mode [String] Optional Available since 1.11.0

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

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

    The possible values are:

    • form_post

    • fragment

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

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

    response_type [String] Required

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

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

    • token - Return an access_token

    • token id_token - Return both the access_token and the id_token

    • id_token - Return an id_token

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

    nonce [String] Optional Available since 1.5.0

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

    scope [String] Optional

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

    Available scopes:

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

    state [String] Optional

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

    tenantId [UUID] Required Available since 1.8.0

    The unique Tenant Id.

    user_code [String] Optional Available since 1.11.0

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

    Response

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

     

    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.

    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.

    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:

    1. The logoutURL of the Application if defined.

    2. The logoutURL configured on the Tenant if defined.

    3. /

    Request

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

    URI

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

    Request Parameters

    client_id [String] Optional

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

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

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

    id_token_hint [String] Optional Available since 1.10.0

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

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

    This parameter is only used if client_id is not provided.

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

    post_logout_redirect_uri [String] Optional Available since 1.10.0

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

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

    state [String] Optional Available since 1.10.0

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

    tenantId [UUID] Required Available since 1.8.0

    The unique Tenant Id used for applying the proper theme.

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

    Available since version 1.37.0

    URI

    POST /oauth2/logout

    Request Body

    client_id [String] Optional

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

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

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

    id_token_hint [String] Optional

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

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

    This parameter is only used if client_id is not provided.

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

    post_logout_redirect_uri [String] Optional

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

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

    state [String] Optional

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

    tenantId [UUID] Required

    The unique Tenant Id used for applying the proper theme.

    Response

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

    URI

    POST /oauth2/token

    Request Headers

    Authorization [String] Optional Available since 1.3.0

    This header is optional if you have provided the client_id in the request body. The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid. Please see the Client Secret section for more details.

    If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character. Here is an example of these two values concatenated.

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

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

    
    Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

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

    Request Headers

    Content-Type [String] Required

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

    Request Body

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

    client_id [String] Optional

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

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

    client_secret [String] Optional Available since 1.5.0

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

    code [String] Required

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

    code_verifier [String] Optional Available since 1.8.0

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

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

    grant_type [String] Required

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

    redirect_uri [String] Required

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

    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.

    URI

    POST /oauth2/token

    Request Headers

    Authorization [String] Optional Available since 1.3.0

    This header is optional if you have provided the client_id in the request body. The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid. Please see the Client Secret section for more details.

    If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character. Here is an example of these two values concatenated.

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

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

    
    Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

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

    Request Headers

    Content-Type [String] Required

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

    Request Body

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

    client_id [String] Optional

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

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

    client_secret [String] Optional Available since 1.5.0

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

    grant_type [String] Required

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

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

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

    For example:

    Erlich’s iPhone
    metaData.device.name [String] Optional Available since 1.20.1

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

    For example:

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

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

    • BROWSER

    • DESKTOP

    • LAPTOP

    • MOBILE

    • OTHER

    • SERVER

    • TABLET

    • TV

    • UNKNOWN

    username [String] Required

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

    password [String] Required

    The user’s password.

    scope [String] Optional

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

    Available grant types:

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

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

    user_code [String] Optional Available since 1.11.0

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

    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.

    URI

    POST /oauth2/token

    Request Headers

    Authorization [String] Optional Available since 1.3.0

    This header is optional if you have provided the client_id in the request body. The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid. Please see the Client Secret section for more details.

    If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character. Here is an example of these two values concatenated.

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

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

    
    Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

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

    Request Headers

    Content-Type [String] Required

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

    Request Body

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

    client_id [String] Optional

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

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

    client_secret [String] Optional

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

    device_code [String] Required
    grant_type [String] Required

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

    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.

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

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

    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.

    URI

    POST /oauth2/token

    Request Headers

    Authorization [String] Optional Available since 1.3.0

    This header is optional if you have provided the client_id in the request body. The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid. Please see the Client Secret section for more details.

    If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character. Here is an example of these two values concatenated.

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

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

    
    Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

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

    Request Cookies

    access_token [String] Optional Available since 1.16.0

    The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the original field. If both the cookie and request parameter are provided, the cookie will take precedence.

    Request Headers

    Content-Type [String] Required

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

    Request Parameters

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

    access_token [String] Optional Available since 1.16.0

    The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the original field.

    client_id [String] Optional

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

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

    client_secret [String] Optional Available since 1.5.0

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

    grant_type [String] Required

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

    refresh_token [String] Required

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

    scope [String] Optional

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

    user_code [String] Optional Available since 1.11.0

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

    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

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

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

    Client Credentials Grant Request

    FusionAuth Reactor logo

    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.

    URI

    POST /oauth2/token

    Request Headers

    Content-Type [String] Required

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

    Request Headers

    Authorization [String] Optional Available since 1.3.0

    This header is optional if you have provided the client_id in the request body. The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid. Please see the Client Secret section for more details.

    If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character. Here is an example of these two values concatenated.

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

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

    
    Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

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

    Request Parameters

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

    client_id [String] Optional

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

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

    client_secret [String] Optional

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

    grant_type [String] Required

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

    scope [String] Optional

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

    You will typically provide a scope specifying the target entity:

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

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

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

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

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

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

    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

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

    Response Body

    access_token [String]

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

    expires_in [Integer]

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

    scope [String]

    The scope value from the request.

    token_type [String]

    The token type. The value will be Bearer.

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

    URI

    POST /oauth2/device_authorize

    Request Headers

    Content-Type [String] Required

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

    Request Parameters

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

    client_id [String] Required

    The unique client identifier. The client Id is the Id of the FusionAuth Application 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

    Response

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

    Response Body

    device_code [String]

    The device verification code.

    expires_in [Integer]

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

    interval [Integer]

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

    user_code [String]

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

    verification_uri [String]

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

    verification_uri_complete [String]

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

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

    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.

    Response

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

    503

    The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

    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

    URI

    POST /oauth2/introspect

    Request Headers

    Content-Type [String] Required

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

    Request Parameters

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

    client_id [String] Required

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

    token [String] Required

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

    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

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

    active [String]

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

    applicationId [UUID]

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

    aud [String]

    The client_id that was used to request the access token.

    authenticationType [String]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    email [String]

    The email address of the User.

    email_verified [Boolean]

    Indicates if the User’s email has been verified.

    exp [Long]

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

    iat [Long]

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

    iss [String]

    The issuer of the access token.

    preferred_username [String] Available since 1.5.0

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

    roles [Array<String>]

    The roles assigned to the User in the authenticated Application.

    sub [UUID]

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

    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
    }

    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.

    URI

    GET /oauth2/userinfo

    Returns the Claims about the authenticated End-User.

    URI

    POST /oauth2/userinfo

    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>

    Response

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

    applicationId [UUID]

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

    birthdate [String] Available since 1.1.0

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

    email [String]

    The email address of the User.

    email_verified [Boolean]

    Indicates if the User’s email has been verified.

    family_name [String] Available since 1.1.0

    The last name of the User if available.

    given_name [String] Available since 1.1.0

    The first name of the User if available.

    name [String] Available since 1.1.0

    The full name of the User if available.

    middle_name [String] Available since 1.1.0

    The middle name of the User if available.

    phone_number [String] Available since 1.1.0

    The phone number of the User if available.

    picture [String] Available since 1.1.0

    A URL to a picture of the User if available.

    preferred_username [String] Available since 1.1.0

    The username of the User if available.

    roles [Array]

    The roles assigned to the User in the authenticated Application.

    sub [UUID]

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

    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.

    URI

    GET /.well-known/jwks.json

    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.

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

    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

    URI

    GET /.well-known/openid-configuration

    Request Parameters

    tenantId [UUID] Optional Available since 1.8.0

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

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

    error [String]

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

    The possible values are:

    • authorization_pending

    • change_password_required

    • expired_token

    • invalid_grant

    • invalid_request

    • invalid_scope

    • invalid_token

    • server_error

    • two_factor_required

    • unauthorized_client

    • unsupported_grant_type

    • unsupported_response_type

    error_description [String]

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

    error_reason [String]

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

    The possible values are:

    • access_token_expired

    • access_token_failed_processing

    • access_token_malformed

    • access_token_unavailable_for_processing

    • auth_code_not_found

    • change_password_administrative

    • change_password_breached

    • change_password_expired

    • change_password_validation

    • client_authentication_missing

    • client_id_mismatch

    • grant_type_disabled

    • invalid_additional_client_id

    • invalid_client_authentication_scheme

    • invalid_client_authentication

    • invalid_client_id

    • invalid_device_code

    • invalid_grant_type

    • invalid_id_token_hint

    • invalid_origin

    • invalid_pkce_code_challenge_method

    • invalid_pkce_code_challenge

    • invalid_pkce_code_verifier

    • invalid_post_logout_redirect_uri

    • invalid_redirect_uri

    • invalid_response_mode

    • invalid_response_type

    • invalid_user_code

    • invalid_user_credentials

    • login_prevented

    • missing_client_id

    • missing_code

    • missing_code_challenge,

    • missing_code_verifier,

    • missing_device_code

    • missing_grant_type

    • missing_redirect_uri

    • missing_refresh_token

    • missing_response_type

    • missing_token

    • missing_user_code

    • missing_verification_uri

    • refresh_token_not_found

    • unknown

    • user_code_expired

    • user_expired

    • user_locked

    • user_not_found

    state [String]

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

    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, 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 or later, use oauthConfiguration.clientAuthenticationPolicy to configure this functionality.

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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates