Settings

Change admin settings.

Changed on Oct 10, 2026

Changes the settings given in the body and leaves the rest as they are. An empty phieldApiKey removes the key. phieldUrl must be an absolute http or https URL, and is required while Phield is enabled; both are checked when a request changes Phield. Each webhookAllowlist entry must be a hostname, an IP address, or a CIDR range. Nothing is changed if any value is invalid. Returns the settings as saved, with warnings, such as a Phield API key that will be sent over http. Recorded as a settings_updated audit event naming the settings that changed and the calling API key, not their values. The read-only crossUserAccessEnabled, ledgerDeletionEnabled, and signingKeyExternallyManaged are ignored. Requires an administrator as well as the scope. Requires the settings:write scope.

patch/api/settings

Request

Base URL
/ (relative, and the document was published on a file host, not at the API’s origin)
URL
/api/settings
Auth
HTTP bearer

Headers

Authorizationstring required

Request body

diffuseCountsEnabledboolean

mfaAvailableboolean

Whether users may enroll in TOTP multi-factor authentication.

mfaRequiredboolean

Whether every user who signs in must enroll in MFA. Requires mfaAvailable.

phieldApiKeystring

phieldEnabledboolean

phieldOrganizationstring

phieldSourceIdstring

phieldUrlstring

signingEnabledboolean

webhookAllowliststring

Response

The settings as saved.

crossUserAccessEnabledboolean

Whether administrators may use owner and all_users to reach other users' resources. Set by ADMIN_CROSS_USER_ACCESS_ENABLED; read-only, and ignored by PATCH.

diffuseCountsEnabledboolean

ledgerDeletionEnabledboolean

Whether administrators may delete and purge ledger chains. Set by LEDGER_DELETION_ENABLED; read-only, and ignored by PATCH.

mfaAvailableboolean

mfaRequiredboolean

phieldApiKeySetboolean

phieldEnabledboolean

phieldOrganizationstring

phieldSourceIdstring

phieldUrlstring

signingEnabledboolean

signingKeyExternallyManagedboolean

Whether the output signing key comes from PHILTER_SIGNING_KEY_PATH, in which case it cannot be rotated through the API. Read-only, and ignored by PATCH.

warningsstring[]