Skip to main content
API7.ai Logo
Version: 3.10.x

Password Policy

Available in API7 Enterprise from version 3.10.10.

A password policy requires built-in users to change their password after a set number of days and stops them from reusing recent passwords. The policy is off by default.

Who the Policy Applies To​

The policy applies to built-in users with a local password, including the default admin account.

It does not apply to users who sign in through SSO or are provisioned through SCIM. Requests authenticated with a token are also unaffected, even when the password of the token's owner has expired.

Configure the Policy​

To turn on the policy in the Dashboard:

  1. In the API7 Dashboard, navigate to Organization > Settings.
  2. On the Login Options tab, find Password Policy and click Enable.
  3. Set Maximum Password Age (days) and Password History Count. The form is pre-filled with 90 days and the saved history count, which is 5 by default.
  4. Click Enable.

Once the policy is on, the card shows both values and its actions menu offers Edit and Disable. Disable asks for confirmation, stops passwords from expiring, and stops the reuse check. It keeps the history count for the next time you enable the policy.

To configure the same setting through the Admin API, send both fields in a PUT request. Both are required. A GET request to the same path returns the current values.

curl -k "https://localhost:7443/api/system_settings/password_policy" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "password_max_age_days": 90,
    "password_history_count": 5
  }'
Dashboard fieldAPI fieldValuesDefaultDescription
Maximum Password Age (days)password_max_age_days0, or 1 to 3650How many days a password stays valid. In the API, 0 turns the policy off. The Dashboard form accepts 1 to 365 and turns the policy off through Disable.
Password History Countpassword_history_count0 to 245How many previous passwords users cannot reuse, in addition to the current one. Only enforced while password_max_age_days is greater than 0. With 0, the new password only has to differ from the current one.
caution

Password age counts from when the password was last set, not from when you enable the policy. A password already older than the maximum age expires as soon as you enable the policy or lower the maximum age.

Required Permissions​

The following actions apply to the arn:api7:iam:organization/* resource. In the permission policy editor, they appear under the Password Policy resource type.

ActionAllows
iam:GetPasswordPolicyViewing the policy. Users without this action do not see the Password Policy card.
iam:UpdatePasswordPolicyChanging the policy.

Each update is recorded in the audit logs with the UpdateSystemSettings event type.

When a Password Expires​

The next time the user logs in, the Dashboard opens the Change Expired Password dialog, which asks for the old password and a new one. If the user is already logged in, their next action or a page refresh opens the same dialog. Until the password is changed, the user can only change the password or log out.

After the change, the old password stops working and all the user's sessions end. The user then logs in with the new password.

An administrator can reset the password of a user who no longer knows the old one. The user then sets a new password at the next login.

HTTP Basic Auth requests that use an expired password are rejected with status 401 and the warning_msg value password expired. The only exception is the change-password call, PUT /api/password. Use tokens for automation so that it does not depend on a password's age.

Password Reuse​

While the policy is on, users changing their own password cannot use their current password or any of the last Password History Count passwords. This includes the forced change after an administrator resets their password. An administrator's reset of another user's password is not checked.

API7 Gateway records replaced passwords even when the policy is off, and keeps up to 24 per user. If you enable the policy later or raise the count, passwords replaced while it was off or set to a lower count are still checked. Passwords replaced before upgrading are not in the history.

Expiry Warning​

From 7 days before a password expires, the Dashboard shows a banner with the remaining time and a Change Password link. The count rounds down, so a freshly changed password under a 7-day policy shows 6 days.

API clients can read the expiry time from the password_expires_at field of GET /api/me. The value is an RFC 3339 UTC timestamp, or null when the password does not expire or the request did not authenticate with a session or Basic Auth.

Upgrade Behavior​

The default is off, so upgrading alone changes nothing. Passwords set before the upgrade count from the moment of the upgrade, so enabling a policy right after upgrading does not immediately expire them.

Next Steps​