Retrieve OAuth Configuration

This API is used to retrieve the Application OAuth configuration. When an API key is provided on the request the OAuth client secret will also be returned. When this API is called without authentication the client secret will not be returned in the response body.

Request#

Retrieve the OAuth Configuration for an Application

GET/api/application/{applicationId}/oauth-configuration

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Parameters#

applicationIdUUIDrequired

The Id of the Application to retrieve the OAuth configuration.

Response#

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

httpSessionMaxInactiveIntervalInteger

The time in seconds until an inactive session will be invalidated, from the application's tenant. Used when creating a new session in the FusionAuth Front End.

logoutURLString

The logout redirect URL when sending the user's browser to the /oauth2/logout URI of the FusionAuth Front End. From the application's tenant.

oauthConfiguration.authorizedOriginURLsArray<String>

An array of URLs that are the authorized origins for FusionAuth OAuth.

When this configuration is omitted, all HTTP origins are allowed to use the browser based grants and the HTTP response header of X-Frame-Options: DENY will be added to each response to disallow iframe loading.

oauthConfiguration.authorizedRedirectURLsArray<String>

An array of URLs that are the authorized redirect URLs for FusionAuth OAuth.

oauthConfiguration.authorizedResourceUrisArray<String>Available since 1.67.0

An array of allowed resource server URIs for this application, per RFC 8707 (Resource Indicators for OAuth 2.0).

Each URI is an absolute URI with no fragment. When this list is non-empty, clients may pass a resource parameter during OAuth authorize and token flows to scope the issued access token to a specific resource server. When empty, any resource parameter sent by the client is silently ignored.

oauthConfiguration.authorizedURLValidationPolicyAvailable since 1.43.0

Controls the validation policy for oauthConfiguration.authorizedOriginURLs and oauthConfiguration.authorizedRedirectURLs.

The possible values are:

ExactMatch - Only the configured values that do not contain wildcards are considered for validation. Values during OAuth 2.0 workflows must match a configured value exactly.
AllowWildcards - Configured values with and without wildcards are considered for validation. Values during OAuth 2.0 workflows can be matched against wildcard patterns or exactly match a configured value.

oauthConfiguration.clientAuthenticationPolicyStringAvailable since 1.28.0

Determines the client authentication requirements for the OAuth 2.0 Token endpoint.

The possible values are:

Required - The client must provide client credentials when using the Token endpoint. The client_id and client_secret may be provided using a Basic Authorization HTTP header, or by sending these parameters in the request body using POST data.
NotRequired - Providing client credentials is optional when using the Token endpoint.
NotRequiredWhenUsingPKCE - The client must provide client credentials when using the Token endpoint unless a valid PCKE code_verifier has been provided in the request body using POST data.

oauthConfiguration.clientIdString

The OAuth client Id of the Application.

oauthConfiguration.clientSecretString

The OAuth client secret. This field will only be provided when the request was authenticated using an API key.

oauthConfiguration.consentModeStringAvailable since 1.50.0

Controls the policy for prompting a user to consent to requested OAuth scopes. This configuration only takes effect when oauthConfiguration.relationship is ThirdParty.

The possible values are:

AlwaysPrompt - Always prompt the user for consent.
RememberDecision - Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the Tenant's externalIdentifierConfiguration.rememberOAuthScopeConsentChoiceTimeToLiveInSeconds value.
NeverPrompt - The user will be never be prompted to consent to requested OAuth scopes. Permission will be granted implicitly as if this were a FirstParty application. This configuration is meant for testing purposes only and should not be used in production.

oauthConfiguration.deviceVerificationURLStringAvailable since 1.11.0

The device verification URL to be used with the Device Code grant type.

oauthConfiguration.enabledGrantsArray<String>Available since 1.5.0

The enabled grants for this application. In order to utilize a particular grant with the OAuth 2.0 endpoints you must have enabled the grant.

Supported values include:

authorization_code
implicit
password
refresh_token
urn:ietf:params:oauth:grant-type:device_code Available since 1.11.0

oauthConfiguration.generateRefreshTokensBooleanAvailable since 1.3.0

Determines if the OAuth 2.0 Token endpoint will generate a refresh token when the offline_access scope is requested.

oauthConfiguration.logoutBehaviorStringAvailable since 1.11.0

Behavior when /oauth2/logout is called.

Valid values:

RedirectOnly: end the SSO session and redirect to the configured Logout URL or the passed in post_logout_redirect_uri value.
AllApplications: end the SSO session and make a GET request to all configured Logout URLs for every application in the tenant.

oauthConfiguration.logoutURLString

The logout URL for the Application. FusionAuth will redirect to this URL after the user logs out of OAuth.

oauthConfiguration.proofKeyForCodeExchangePolicyStringAvailable since 1.28.0

Determines the PKCE requirements when using the authorization code grant.

The possible values are:

Required - The client must provide a valid code_verifier on the request body when completing the authorization code grant.
NotRequired - Providing a code_verifier is optional when completing the authorization code grant.
NotRequiredWhenUsingClientAuthentication - The client must provide a valid code_verifier on the request body when completing the authorization code grant unless valid client credentials have been provided using a Basic Authorization HTTP header, or by sending these parameters in the request body using POST data.

oauthConfiguration.providedScopePolicy.address.enabledBooleanAvailable since 1.50.0

Whether the address OAuth scope provided by FusionAuth is enabled for this application.

oauthConfiguration.providedScopePolicy.address.requiredBooleanAvailable since 1.50.0

Whether consent to the address OAuth scope provided by FusionAuth is required for this application when present on the OAuth request.

oauthConfiguration.providedScopePolicy.email.enabledBooleanAvailable since 1.50.0

Whether the email OAuth scope provided by FusionAuth is enabled for this application.

oauthConfiguration.providedScopePolicy.email.requiredBooleanAvailable since 1.50.0

Whether consent to the email OAuth scope provided by FusionAuth is required for this application when present on the OAuth request.

oauthConfiguration.providedScopePolicy.phone.enabledBooleanAvailable since 1.50.0

Whether the phone OAuth scope provided by FusionAuth is enabled for this application.

oauthConfiguration.providedScopePolicy.phone.requiredBooleanAvailable since 1.50.0

Whether consent to the phone OAuth scope provided by FusionAuth is required for this application when present on the OAuth request.

oauthConfiguration.providedScopePolicy.profile.enabledBooleanAvailable since 1.50.0

Whether the profile OAuth scope provided by FusionAuth is enabled for this application.

oauthConfiguration.providedScopePolicy.profile.requiredBooleanAvailable since 1.50.0

Whether consent to the profile OAuth scope provided by FusionAuth is required for this application when present on the OAuth request.

oauthConfiguration.relationshipStringAvailable since 1.50.0

The application's relationship to the authorization server.

The possible values are:

FirstParty - The application has the same owner as the authorization server. Consent to requested OAuth scopes is granted implicitly.
ThirdParty - The application is external to the authorization server. Users will be prompted to consent to requested OAuth scopes based on oauthConfiguration.consentMode.

oauthConfiguration.requireClientAuthenticationBooleanAvailable since 1.3.0DEPRECATED

Determines if the OAuth 2.0 Token endpoint requires client authentication. If this is enabled, the client must provide client credentials when using the Token endpoint. The client_id and client_secret may be provided using a Basic Authorization HTTP header, or by sending these parameters in the request body using POST data.

Deprecated since 1.28.0

In version 1.28.0 and beyond, client authentication can be managed via oauthConfiguration.clientAuthenticationPolicy.

oauthConfiguration.requireRegistrationBooleanAvailable since 1.28.0

Determines if the user will be required to be registered, or complete registration before redirecting to the configured callback in the authorization code grant or the implicit grant. This configuration does not affect any other grant, and does not affect the API usage.

oauthConfiguration.scopeHandlingPolicyStringAvailable since 1.50.0

Controls the policy for handling of OAuth scopes when populating JWTs and the UserInfo response.

The possible values are:

Compatibility - OAuth workflows will populate JWT and UserInfo claims in a manner compatible with versions of FusionAuth before version 1.50.0.
Strict - OAuth workflows will populate token and UserInfo claims according to the OpenID Connect 1.0 specification based on requested and consented scopes.

oauthConfiguration.unknownScopePolicyStringAvailable since 1.50.0

Controls the policy for handling unknown scopes on an OAuth request.

The possible values are:

Allow - Unknown scopes will be allowed on the request, passed through the OAuth workflow, and written to the resulting tokens without consent.
Remove - Unknown scopes will be removed from the OAuth workflow, but the workflow will proceed without them.
Reject - Unknown scopes will be rejected and cause the OAuth workflow to fail with an error.

Example Response JSON

{
  "httpSessionMaxInactiveInterval": 3600,
  "logoutURL": "http://www.example.com/logout",
  "oauthConfiguration": {
    "authorizedOriginURLs": [
      "http://www.example.com"
    ],
    "authorizedRedirectURLs": [
      "http://www.example.com/oauth-callback"
    ],
    "authorizedURLValidationPolicy": "ExactMatch",
    "clientAuthenticationPolicy": "Required",
    "clientId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
    "consentMode": "AlwaysPrompt",
    "enabledGrants": [
      "authorization_code",
      "refresh_token"
    ],
    "generateRefreshTokens": true,
    "logoutBehavior": "AllApplications",
    "logoutURL": "http://www.example.com/logout",
    "proofKeyForCodeExchangePolicy": "NotRequired",
    "providedScopePolicy": {
      "address": {
        "enabled": true,
        "required": false
      },
      "email": {
        "enabled": true,
        "required": false
      },
      "phone": {
        "enabled": true,
        "required": false
      },
      "profile": {
        "enabled": true,
        "required": false
      }
    },
    "relationship": "FirstParty",
    "requireClientAuthentication": true,
    "requireRegistration": false,
    "scopeHandlingPolicy": "Compatibility",
    "unknownScopePolicy": "Reject"
  }
}