Applications
Overview
A FusionAuth Application is simply something a user can log into. When you use the Login API, you will provide an applicationId
to indicate what resource you’re attempting to obtain authorization. When you use one of the OAuth2 / OpenID Connect authorization grants you will provide a client_id
in some fashion. This client identifier will be unique to a single FusionAuth Application which allows FusionAuth to verify the User is registered for the requested Application and subsequently return the correct roles. The applicationId
and client_id
can be considered synonymous, both concepts use the same Id
value.
A FusionAuth Application holds configuration for how your applications interact with FusionAuth. A one to one mapping between an external web, mobile or desktop application and a FusionAuth Application is not required. All of these mappings are supported:
- One to one. Each application has one Application configuration.
- Many to one. Multiple web and mobile applications use one FusionAuth Application config.
- One to many. One web application can auth against multiple FusionAuth Applications, if different authentication scenarios needed to be handled in one application (this isn’t very common, though).
Here’s a brief video covering some aspects of applications:
Core Concepts Relationships
Below is a visual reminder of the relationships between FusionAuth’s primary core concepts.
Admin UI
This page describes the Admin UI for creating and configuring an Application.
Add an Application
Before you start your integration with FusionAuth you need to set up at least one Application. Click on Applications from the left navigation to begin.

Form Fields
An optional UUID. When this value is omitted a unique Id will be generated automatically. This will also be used as the Client Id in the OAuth configuration, so if you require a specific value for that, set it here.
The name of the Application. This value is for display purposes only and can be changed at any time.
The tenant in which to create this Application.
This field is only displayed once multiple tenants exist in FusionAuth. When only a single tenant exists, the Application will always be created in the default tenant.
When a theme is selected, it will be used for this application instead of the tenant theme.
Note: A paid plan is required to utilize application themes.Roles
The Roles tab will only be available on the Add Application form. To manage roles after the Application has been created you will use the Manage Roles action.
Table Columns
The name of the role. This value should be short and descriptive. Roles can only be created and deleted, only the role description may be modified.
One or more roles may be marked as default. A default role will be automatically added to new user registrations when no roles are explicitly provided on the API request.
A role may be optionally marked as a super user role. This indicator is just a marker to indicate to you that this role encompasses all other roles. It has no effect on the usage of the role.
An optional description to better describe the intended use of this role.
To manage Application Roles after you have added an Application, click the Manage Roles button on the index page. To edit an Application click the edit icon. The following sections will walk you through each panel for the edit action.

OAuth
The OAuth tab allows you to configure the OAuth2 and OpenID Connect settings specific to this Application.

Form Fields
The read only client Id for this Application. The client Id is used by OAuth2 / OpenID Connect to authenticate the grant request.
The read only client secret used for client authentication. When you enable Require authentication, this client secret will be required to obtain an access token from the Token endpoint.
You may optionally regenerate the client secret if you think it has been compromised.
This selector allows you to set a rule for accessing the Token endpoint.
- Required - The
client_secret
parameter must be used. This is the default setting. In most cases you will not want to change this setting. - Not required - Use of the
client_secret
parameter is optional. - Not required when using PKCE - Requires the use of the
client_secret
parameter unless a valid PKCE code_verifier parameter is used. This is useful for scenarios where you have a requirement to make a request to the Token endpoint where you cannot safely secure a client secret such as native mobile applications and single page applications (SPAs) running in a browser. In these scenarios it is recommended you use PKCE.
See the Token endpoint for more information.
This selector allows you to set a rule for Proof Key for Code Exchange (or PKCE) requirements when using the authorization code grant.
- Required - The
code_verifier
parameter must be used. If you want to require PKCE for this application, set PKCE to this value. - Not required - Use of the
code_verifier
parameter is optional. This is the default setting. - Not required when using client authentication - Requires the use of the
code_verifier
parameter unless a validclient_secret
parameter is used.
When enabled, FusionAuth will return a refresh token when the offline_access
scope has been requested. When this setting is disabled refresh tokens will not be generated even if the offline_access
scope is requested.
Enable debug to create an event log to assist you in debugging integration errors.
Controls the validation policy for Authorized redirect URLs and Authorized request origin URLs .
The possible values are:
Exact match
- 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.Allow wildcards
- 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.
When OAuth grants, such as the authorization code grant, require a browser redirect to a URL found in the redirect_uri
parameter, the destination URLs must be added to this list. URLs that are not authorized may not be utilized in the redirect_uri
parameter or the post_logout_redirect_uri
parameter.
You can add as many URLs as you’d like to this list. Prior to version 1.43.0
only exact string matches with the provided redirect_uri
will be allowed. No partial or wildcard matches will be accepted.
Configured URLs containing wildcards are considered during validation when Authorized redirect URLs is set to Allow wildcards
. Wildcards are allowed in the following positions:
- The left-most subdomain - A full or partial wildcard is allowed in the left-most subdomain. The replacement value cannot contain a
.
. - The port number - A wildcard is allowed in place of the port number. Partial wildcards are not allowed in this position.
- A path segment - A full or partial wildcard is allowed in any path segment. The replacement value cannot contain a
/
. - A query string value - A wildcard is allowed in place of a query string value. Partial wildcards are not allowed in this position. Wildcards are not allowed in query string names.
See the OAuth 2.0 URL Validation page for more detail.
This optional configuration allows you to restrict the origin of an OAuth2 / OpenID Connect grant request. If no origins are registered for this Application, all origins are allowed.
By default FusionAuth will add the X-Frame-Options: DENY
HTTP response header to the login pages to keep these pages from being rendered in an iframe. If the request comes from an authorized origin, however, FusionAuth will not add this header to the response. To load FusionAuth hosted login pages in an iframe, you will need to add the request origin to this configuration.
Configured URLs containing wildcards are considered during validation when Authorized request origin URLs is set to Allow wildcards
. Wildcards are allowed in the following positions:
- The left-most subdomain - A full or partial wildcard is allowed in the left-most subdomain. The replacement value cannot contain a
.
. - The port number - A wildcard is allowed in place of the port number. Partial wildcards are not allowed in this position.
- A path segment - A full or partial wildcard is allowed in any path segment. The replacement value cannot contain a
/
. - A query string value - A wildcard is allowed in place of a query string value. Partial wildcards are not allowed in this position. Wildcards are not allowed in query string names.
See the OAuth 2.0 URL Validation page for more detail.
The optional logout URL for this Application. When provided this logout URL should handle the logout of a user in your application.
If you need to end an HTTP session, or delete cookies to logout a user from your application, these operations should be handled by this URL. When the /oauth2/logout
endpoint is utilized, each Logout URL registered for Applications in this tenant will be called within an iframe to complete the SSO logout.
If the OAuth2 logout endpoint is used with this Client Id, this configured Logout URL will be also utilized as the redirect URL. This behavior only occurs when the post_logout_redirect_uri
parameter is not provided.
If this Application has not defined a Logout URL, the value configured at the Tenant level will be used. If no Logout URL has been configured, a redirect to /
will occur. A specific redirect URL may also be provided by using the post_logout_redirect_uri
request parameter.
See the Logout endpoint for more information.
This selector allows you to modify the behavior when using the Logout endpoint with this Client Id.
- All applications - This is the default behavior. Upon Logout of the FusionAuth SSO, call each registered Logout URLs for the entire tenant and then redirect to the Logout URL registered for this application.
- Redirect only - Do not call each registered Logout URL in the tenant, instead logout out of the FusionAuth SSO and then only redirect to the Logout URL registered for this application.
See the Logout endpoint for more information.
The enabled OAuth2 grants. If a grant is not enabled and a client requests this grant during authentication an error will be returned to the caller indicating the grant is not enabled.
- Authorization Code
- Device
- Implicit
- Password
- Refresh Token
See The OAuth 2.0 & OpenID Connect Overview for additional information on each of these grants.
When enabled 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.
When you enable the Device
grant you will be shown one additional configuration field:

Form Fields
The URL to be returned during the Device Authorization request to be displayed to the end user. This URL will be where the end user navigates in order to complete the device authentication workflow.
Required when the Device
grant has been enabled.
CleanSpeak
The CleanSpeak configuration panel allows you to optionally configure username filtering through the use of a CleanSpeak integration. See CleanSpeak Integration for additional configuration details.
The use of this feature requires a licensed instance of CleanSpeak. See https://cleanspeak.com for additional information.

The email configuration allows you to optionally select customized email templates for this Application. When configured, an application specific template will be used instead of the tenant configured email template.

Form Fields
The email template to use when notifying a user that their email address has been updated.
Note: An Enterprise plan is required to utilize this feature.The email template to use when accounts are created to verify the User’s email address.
The email template to use when notifying a user that email address has been verified.
Note: An Enterprise plan is required to utilize this feature.The email template to use for the forgot password workflow.
The email template to use when notifying a user that another user has attempted to register an account with the same username or email address as they have. If user Richard has an email richard@piedpiper.com
and a new user tries to register with the email address richard@piedpiper.com
, then user Richard will be notified.
The email template to use when notifying a user that another user has attempted to change their own email or username to a value in-use by the user.
Note: An Enterprise plan is required to utilize Login Id duplicate on update.The email template to use when notifying a user that a new device was used to login.
Note: An Enterprise plan is required to utilize Login with new device.The email template to use when notifying a user that a login occurred and it was determined to be of interest or suspect due to the location, IP address or other factors.
Note: An Enterprise plan is required to utilize Suspicious login.The email template to use when notifying a user that their password has been successfully updated using the reset workflow.
Note: An Enterprise plan is required to utilize Password reset success.The email template to use when notifying a user that their password has been successfully updated. This is different from Password reset success in that this event occurs outside of the reset workflow.
Note: An Enterprise plan is required to utilize Password update.The template to use to send the link for passwordless login requests.
The email template to use when accounts are created and the user needs to setup their password.
The email template to use when notifying a user that a new two-factor method has been successfully added.
Note: An Enterprise plan is required to utilize Two-factor method added.The email template to use when notifying a user that a previously configured two-factor method has been successfully removed.
Note: An Enterprise plan is required to utilize Two-factor method removed.JWT
The JWT configuration allows you to provide application specific JWT configuration. When this panel is left in the default state as shown in this screenshot without the enable toggle turned on, the JWT configuration provided by the Tenant will be utilized.

When enabled you may configure Application specific JWT configuration including signing keys, durations, etc.
Lambda Settings
The application specific lambda settings are available even if you choose not to enable additional application specific JWT configuration by leaving the Enable field off.
The lambda to be invoked during the generation of an Access Token (JWT) when a user authenticates against this Application.
The lambda to be invoked during the generation of an Id Token (JWT) when a user authenticates against this Application.
Once you have enabled JWT configuration for this Application you will be provided with additional configuration options.

JWT Settings
The issuer used in the iss
claim when building the Access Token and Id Token. This is a read-only value in this configuration. It can be modified in the Tenant configuration.
The duration in seconds for which a JWT will be valid after creation. After this time has passed the JWT will expire and can no longer be used.
The signing key used to sign the Access Token (which is a JWT) when a user authentic The signing key used to sign the Access Token (which is a JWT) when a user authenticates against this Application. When this value is not selected, FusionAuth will generate a new key pair and assign it to this configuration.
The signing key used to sign the Id Token (which is a JWT) when a user authenticates against this Application. When this value is not selected, FusionAuth will generate a new key pair and assign it to this configuration.

Refresh Token Settings
The length of time the refresh token is valid. Refresh tokens are typically long lived.
The Refresh token expiration may be either a fixed window, sliding window, or sliding window with a maximum lifetime. By default, the expiration of a refresh token is a fixed length of time from when it was originally issued. With a sliding window expiration, the expiration is calculated from the last time the refresh token was used. However with a sliding window with a maximum lifetime, the expiration is calculated from the last time the refresh token was used until a maximum lifetime value is reached.
For instance, consider the following scenarios given the above configuration. If a refresh token is issued at 1:00pm and has a duration of 60 minutes, if the expiration is fixed, the token will expire at 2:00pm. If, instead, the expiration is a sliding window, then if the refresh token is used at 1:55pm, it would then expire at 2:55pm. If it were then used at 2:50pm, it would expire at 3:50 pm. Lastly if the expiration is a sliding window with a maximum lifetime of 24 hours, then the token could be refreshed every hour (in the same sliding manner as outlined above) up to 23 times. For instance, if a token was issued at 1:55pm on Monday and refreshed every hour, the 23th refresh it would be the last valid refresh request (12:55pm Tuesday would be the last valid refresh event).
The Refresh token usage may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use.
Multi-Factor
This feature is only available in paid plans. Please visit our pricing page to learn more.
The multi-factor configuration allows you to provide Application specific multi-factor settings.

Form Fields
When set to Enabled
a two-factor challenge will be required during login when a user has configured one or more two-factor methods. When set to Disabled
, even when a user has one or more two-factor methods configured, a two-factor challenge will not be required during login. When set to Required
, a two-factor challenge will be required during login. If a user does not have configured two-factor methods, they will not be able to log in.
Supported values include:
- No application policy selected. Multi-factor authentication is managed by the tenant.
- Enabled. A challenge will be required during login when an eligible method is available.
- Disabled. A challenge will not be required during login.
- Required. A challenge will be required during login. available since 1.42.0
When On login policy is set to Enabled
, the following field will be displayed. This value will control how the two-factor trust value is utilized.
Supported values include:
- Any. Trust obtained from any application is sufficient to bypass the challenge during login.
- This Application. Only trust obtained from this application is sufficient to bypass to challenge during login.
- None. The user will always be prompted to complete a challenge during login.
When a template is selected, it will be used to send a multi-factor authentication code when the email MFA method is used and a user is signing in to this application.
When a template is selected, it will be used to send a multi-factor authentication code when the SMS MFA method is used and a user is signing in to this application.
WebAuthn
This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.
The WebAuthn configuration allows you to configure which WebAuthn workflows are enabled for the Application, overriding the Tenant configuration.

Form Fields
When disabled, the tenant configuration for enabled WebAuthn workflows will be used. When enabled, the options on this page will be used to override which WebAuthn workflows are enabled for this application.
Bootstrap settings
The bootstrap workflow is used when the user must “bootstrap” the authentication process by identifying themselves prior to the WebAuthn ceremony and can be used to authenticate from a new device using WebAuthn.
Form Fields
When enabled, users will be able to use the WebAuthn bootstrap workflow to sign in, including on new devices.
Re-authentication settings
The re-authentication workflow is used to streamline the login process for repeat logins on a device.
Form Fields
When enabled, users will be able to use the WebAuthn re-authentication workflow for repeat logins on their device.
Registration
The registration configuration allows you to provide Application specific registration configuration.

Form Fields
When enabled a registration can be verified using an email workflow. This is similar to the email verification process, which occurs when a user is first created. Verifying a registration allows you to send an email to an end user and allows them to confirm they registered for this specific application.
The email template to be used when sending the Registration Verification email to the end user.
Required when Verify registrations field toggle has been enabled.
When enabled, the system will delete registrations for users who have not verified their registration for this application after a configurable duration since the registration occurred.
The duration in days for which a user’s registration to this application must exist and remain unverified before being deleted.
Required when Delete unverified registrations field toggle has been enabled.
Self Service Registration
Self service registration allows users to register for this application themselves. If this is not enabled, users must be created using the APIs or the administrative user interface.
There are two types of self service registration, basic and advanced.

Form Fields
When enabled, a button on the login page will be rendered to allow users to create a new account.
Select Basic
or Advanced
self service registration forms.
A paid edition of FusionAuth is required to use the Advanced self service registration forms.

Basic Self Service Registration
Toggle this field if you want FusionAuth to require a password confirmation during registration.
This field indicates if the email address or username should be the user’s unique identifier.
The optional fields to be displayed on the registration form.
The user attribute that can be shown on the registration form. Each field can be Enabled and/or Required .
This field will be shown on the registration form.
This field will be required and the user will be unable to complete registration unless the field is provided. If this field is not also Enabled then it will not be required.

Advanced Self Service Registration
This feature is only available in paid plans. Please visit our pricing page to learn more.
Advanced self service registration allows you to create a custom registration form, including validation, custom form fields, and multiple steps. Learn more in the guide.
When enabled, a button on the login page will be rendered to allow users to create a new account.
The selected form will be used to provide self service registration for this application.
The lambda that will be used to perform additional validation on registration form steps. See Self-Service Registration Validation lambda

Form Settings
This feature is only available in paid plans. Please visit our pricing page to learn more.
The form that will be used in the FusionAuth UI for adding and editing user registrations.
The form that will be used with the hosted login pages for user self-service account management.
When enabled a user will be required to provide their current password when changing their password on a self-service account form.
SAML
The SAML configuration allows you to reveal FusionAuth as a SAML v2 Identity Provider (IdP).

When enabled you may configure FusionAuth to reveal this application as a SAML v2 Identity Provider (IdP).
Once you have enabled SAML for this Application you will be provided with additional configuration options.

Form Fields
The issuer used by service providers (i.e. Google, Zendesk, etc.) to identify themselves to FusionAuth’s SAML identity provider. Often you cannot set this in the service provider and need to read their documentation or test the integration and use the error messages to determine the correct value.
Some service providers require a different audience (such as Zendesk). You can leave this blank if the audience is the same as the issuer.
One or more allowed URLs that FusionAuth may redirect to after the user has logged in via SAML v2, also known as the Assertion Consumer Service URL (ACS).
The URL that the user is redirected to after they are logged out. Usually this is the starting location of the application.
Enable debug to create an event log to assist you in debugging integration errors.

Authentication Request
When enabled, all unsigned requests will be rejected.
The verification key used to verify a signature when the SAML v2 Service Provider is using HTTP Redirect Bindings. +
When HTTP POST Bindings are used, this is the default verification key used if a KeyInfo
element is not found in the SAML AuthNRequest. If a KeyInfo
element is found, Key Master will be used to resolve the key and this configuration will not be used to verify the request signature.
This field is required when Require signature is enabled.
When enabled, FusionAuth will accept a username or email address as a login hint on a custom HTTP request parameter.
The name of the login hint parameter provided by the service provider on an AuthnRequest. If this parameter is present, its value will be used to pre-populate the username field on the FusionAuth login form.
For example, suppose Enable login hint is enabled and Login hint parameter name has the value login_name
. When FusionAuth is set up as an IdP, the SP can send a request which includes the parameter login_name=richard@example.com
, and FusionAuth will pre-populate richard@example.com into the login form the end user sees.
Note that this setting names an HTTP query parameter, not an element in the SAML AuthnRequest XML.

Authentication Response
The signing key used to sign the SAML request. When this value is not selected the default selection will cause FusionAuth to generate a new key pair and assign it to this configuration.
The XML signature canonicalization method. If you are unsure which method to select, leave the default and begin testing, or contact your service provider for configuration assistance.
The location of the XML signature in the SAML response.
The lambda used to add additional values from the user and registration to the SAML response.
When enabled, FusionAuth will be able to initiate a login request to a SAML v2 Service Provider.
Once enabled, open the View dialog or this application to view the integration URI. You will find this value in the view dialog in the SAML v2 Integration details, and the value will be named Initiate login URL: .
The NameId format to send in the AuthN response to the SAML v2 Service Provider. There are two valid values:
- Persistent - The
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
NameID format will be used. - Email - The
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
NameID format will be used.

Logout Request
When enabled the SAML service provider (SP) will be required to sign the Logout request. All unsigned Logout requests will be rejected.
The unique Id of the Key used to verify the signature if the public key cannot be determined by the KeyInfo element when using POST bindings, or the key used to verify the signature when using HTTP Redirect bindings.
This field is required when Require signature is enabled.
This selector allows you to modify the behavior when logout occurs. There are two valid values:
- All session participants - This is the default behavior. Each session participant that has enabled single logout will be sent a Logout Request.
- Only logout request originator - no other session participants will be notified when a logout request is sent for this application.
Enable this to receive a LogoutRequest as a session participant when any other SAML enabled application within the same tenant receives a LogoutRequest.
The URL where you want to receive the LogoutRequest from FusionAuth.
This field is required when Enable single logout is enabled.
The Key used to sign the SAML Single Logout response.
The XML signature canonicalization method. If you are unsure which method to select, leave the default and begin testing, or contact your service provider for configuration assistance.

Logout Response
The signing key used to sign the SAML logout request. When this value is not selected the Authentication Response Signing key will be used.
The XML signature canonicalization method. If you are unsure which method to select, leave the default and begin testing, or contact your service provider for configuration assistance.

Assertion Encryption
When enabled, assertions in SAML responses will be encrypted.
The symmetric key encryption algorithm used to encrypt the SAML assertion.
The location that the encrypted symmetric key information will be placed in the SAML response in relation to the EncryptedData
element containing the encrypted assertion value.
The encryption algorithm used to encrypt the symmetric key for transport in the SAML response.
The message digest algorithm to use when encrypting the symmetric key for transport.
The mask generation function and hash function to use for the Optimal Asymmetric Encryption Padding when encrypting a symmetric key for transport. This configuration is only available when Key transport algorithm is set to RSA OAEP with MGF1
.
The RSA certificate from Key Master that will be used to encrypt the SAML assertion encryption symmetric key for transport.
This field is required when SAML assertion encryption is enabled.
Security
The security tab contains some additional security configuration for this application.

Login API Settings
When enabled the Login API will require an API key. This is functionally equivalent to requiring client authentication during OAuth2.
When enabled the Login API will return refresh tokens. This is functionally equivalent to requesting the offline_scope during an OAuth2 grant.
When enabled a JWT may be refreshed using the JWT Refresh API. This is functionally equivalent to enabling the OAuth2 Refresh Grant.
Access control lists settings
This feature is only available in paid plans. Please visit our pricing page to learn more.
The IP access control list that will be used to restrict or allow access to hosted login pages in FusionAuth. Using this, you can allow access to or block specific IP addresses from an application’s authentication pages (login, forgot password, etc).
When configured, this value will override the IP access control list configuration on the tenant.
Passwordless Login
When enabled, allow users to request login using a link sent via email. Enabling this feature will cause a button to be displayed on the FusionAuth login form and allow you to utilize the Passwordless Login API.
Authentication Tokens
When enabled, allow users to optionally authenticate using an Application specific token in place of their password. This should only be used when the security requirements are low and the user’s normal password is not a good option for authentication.
For example, if a password needs to be stored in an external configuration and the exposure risk is low, a token can be used in place of the user’s password. This token may only be used for authorization for this application.
Webhooks
This feature is removed as of version 1.37.0.
The Webhooks tab allows you to select one or more webhooks to be used for this Application. In this example screenshot either no webhooks have been configured, or no application specific webhooks are configured.

In most cases you will not need to configure this panel. Only a few specific events are considered application specific, and when a webhook is configured to be application specific, only those events will be sent to the webhook.
This example screenshot shows one Application specific webhook selected. This option will be visible if at least one webhook is configured as application specific.
