---
title: "Change admin settings."
method: PATCH
path: "/api/settings"
tags: ["Settings"]
---

# Change admin settings.

`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

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.

## Headers

- `Authorization` string, required

## Request body

- UpdateSettingsRequest
  - `diffuseCountsEnabled` boolean
  - `mfaAvailable` boolean: Whether users may enroll in TOTP multi-factor authentication.
  - `mfaRequired` boolean: Whether every user who signs in must enroll in MFA. Requires mfaAvailable.
  - `phieldApiKey` string
  - `phieldEnabled` boolean
  - `phieldOrganization` string
  - `phieldSourceId` string
  - `phieldUrl` string
  - `signingEnabled` boolean
  - `webhookAllowlist` string

## Response `200`

The settings as saved.

- SettingsResponse
  - `crossUserAccessEnabled` boolean: 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.
  - `diffuseCountsEnabled` boolean
  - `ledgerDeletionEnabled` boolean: Whether administrators may delete and purge ledger chains. Set by LEDGER_DELETION_ENABLED; read-only, and ignored by PATCH.
  - `mfaAvailable` boolean
  - `mfaRequired` boolean
  - `phieldApiKeySet` boolean
  - `phieldEnabled` boolean
  - `phieldOrganization` string
  - `phieldSourceId` string
  - `phieldUrl` string
  - `signingEnabled` boolean
  - `signingKeyExternallyManaged` boolean: 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.
  - `warnings` string[]
  - `webhookAllowlist` string

## Other responses

- `400`: A value is invalid. The body says which, and nothing was changed.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: The key does not hold settings:write, or the caller is not an administrator.
- `404`: Not Found
- `406`: No representation matches Accept.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-10** `c4f85daa9208`: 15 info
  - added the non-success response with the status `404`
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `403` status
  - …11 more
- **2026-10-06** `91ce57908475`: 3 info
  - added the optional property `crossUserAccessEnabled` to the response with the `200` status
  - added the optional property `ledgerDeletionEnabled` to the response with the `200` status
  - added the optional property `signingKeyExternallyManaged` to the response with the `200` status
- **2026-10-05** `4082c17721d8`: 6 breaking, 6 info
  - removed the media type `*/*` for the response with the status `400`
  - removed the media type `*/*` for the response with the status `401`
  - removed the media type `*/*` for the response with the status `413`
  - removed the media type `*/*` for the response with the status `415`
  - …8 more
- **2026-10-05** `2cd7275cfcb5`: 4 info
  - added the new optional request property `mfaAvailable`
  - added the new optional request property `mfaRequired`
  - added the optional property `mfaAvailable` to the response with the `200` status
  - added the optional property `mfaRequired` to the response with the `200` status
- **2026-10-05** `248d2f12d472`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/settings/patch.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)