Skip to content

docs: update flexible pw policy API instructions #1198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hazel-nut merged 1 commit into from
May 18, 2026
Merged

docs: update flexible pw policy API instructions #1198

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 44 additions & 18 deletions main/docs/authenticate/database-connections/flexible-password-policy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The Flexible Password Policy replaces the [legacy password policies](/docs/authe
| Password dictionary | Uses one built-in dictionary of 10,000 common words. | Choose between two built-in dictionaries of 10,000 or 100,000 common words. |
| Block personal data | Blocks a fixed set of user data fields. | Fully customize which fields to block, up to 12. |

In the Management API's configuration schema for database connections, the Flexible Password Policy also replaces the legacy password policy `options` objects and values with a single, configurable `password_options` object.
In the Management API's configuration schema for database connections, the Flexible Password Policy also replaces the legacy password policy `options` objects and attributes with a single, configurable `options.password_options` object.

## Prerequisites

Expand Down Expand Up @@ -109,29 +109,30 @@ After you modify these settings, click **Save**.
</Tab>

<Tab title="Management API">
To enable the Flexible Password Policy using the Management API, you need update your database connection's `options` configuration:
In your database connection's configuration, the `options` object contains its password policy settings. The Flexible Password Policy replaces legacy password objects and attributes in `options` with a single object (`options.password_options`) that has more granular settings.

1. First, get your database connection's current configuration using the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id).
To enable the Flexible Password Policy using the Management API:

2. In the `options` object, remove the following legacy password objects and values:
<Steps>

* `passwordPolicy`
* `password_complexity_options`
* `password_history`
* `password_no_personal_info`
* `password_dictionary`
<Step title="Get the current database connection configuration">
First, get your database connection's current configuration using the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id).

3. In the `options` object, append a single `password_options` object containing your desired Flexible Password Policy configuration.
Save the entire configuration in the response. You can review the response body schema in the endpoint documentation.
</Step>

You can view the full schema for the `password_options` object in the API reference (as in the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) body parameters).
<Step title="Replace legacy settings with Flexible Password Policy settings">
In the `options` object of the configuration, remove the following legacy password objects and values, and then append a single `password_options` object with your desired Flexible Password Policy configuration.

4. Update your database connection with the new `options` object using the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id).
| Legacy `options` attribute | Flexible Password Policy `options` attribute |
|-------------------------------|------------------------------------|
| `password_complexity_options` | `password_options.complexity` |
| `password_history` | `password_options.history` |
| `password_no_personal_info` | `password_options.profile_data` |
| `password_dictionary` | `password_options.dictionary` |
| `passwordPolicy` | Removed |

<Warning>
This endpoint overwrites the entire `options` object with the version you provide, so include the entire modified object in your `PATCH` request to preserve your database connection's other configuration.
</Warning>

As an example, the following two `options` configurations (one legacy, one Flexible Password Policy) both prevent users from using their five most recent passwords, any words in the 10,000 common words list, or the additional entries `badPassword` and `reallyBadPassword`:
As an example, the following two `options` password configurations are equivalent:

<Columns cols={2}>
<div>
Expand Down Expand Up @@ -170,7 +171,32 @@ As an example, the following two `options` configurations (one legacy, one Flexi
</div>
</Columns>

You can verify the update by getting your database connection's configuration with the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) again. If the response contains the `password_options` object, the Flexible Password Policy is enabled for that database connection.
You can view the full schema for the `password_options` object in the API reference (as in the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) body parameters).
</Step>

<Step title="Optionally update other password settings">
Other password attributes outside of the `password_options` object remain unchanged, but are visible in the the Auth0 Dashboard's Flexible Password Policy settings:

| Management API `options` attribute | Auth0 Dashboard setting |
|--------------------------|-------------------------|
| `authentication_methods.password.enabled` | Policy > Password for login |
| `authentication_methods.password.signup_behavior` | Policy > Password on signup |
| `authentication_methods.password.api_behavior` | Policy > Support users without a password |
| `disable_self_service_change_password` | Policy > Self-service change password |

You can optionally update these attributes to modify your configuration.
</Step>

<Step title="Update the database connection">
Update your database connection with the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id).

<Warning>
This endpoint overwrites the existing configuration with configuration you send, so include the entire modified object in your `PATCH` request to preserve your database connection's other settings.
</Warning>
</Step>
</Steps>

You can verify the update by getting your database connection's configuration again with the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id). If the response contains the `options.password_options` object, the Flexible Password Policy is enabled for that database connection.
</Tab>

</Tabs>
Expand Down
Loading