Skip to content

Settings API

These endpoints read and change the deployment's admin settings: differential-privacy count recording, output signing, the webhook destination allowlist, Phield publishing, and MFA. Reading also reports which features the deployment's environment variables turn on. They require an administrator in addition to the scope: settings:read to read, settings:write to change.

The settings object

{
  "diffuseCountsEnabled": false,
  "signingEnabled": true,
  "webhookAllowlist": "hooks.example.com, 10.4.0.0/16",
  "phieldEnabled": true,
  "phieldUrl": "https://phield.example.com",
  "phieldSourceId": "philter",
  "phieldOrganization": "philter",
  "phieldApiKeySet": true,
  "mfaAvailable": false,
  "mfaRequired": false,
  "warnings": [],
  "crossUserAccessEnabled": false,
  "ledgerDeletionEnabled": false,
  "signingKeyExternallyManaged": false
}
  • diffuseCountsEnabled - Record PII counts for differential-privacy reporting. Read them with the PII Counts API.
  • signingEnabled - Sign every text filter and explain response. See Output Signing.
  • webhookAllowlist - Where a user's webhook may point: comma-separated hostnames, IP addresses, and CIDR ranges. Empty allows any public address; private, shared, loopback, link-local, reserved and other special-purpose addresses are refused unless listed.
  • phieldEnabled, phieldUrl, phieldSourceId, phieldOrganization - Phield publishing.
  • phieldApiKeySet - Whether a Phield API key is set. The key itself is never returned.
  • mfaAvailable - Whether users may enroll in TOTP multi-factor authentication for sign-in. Users already enrolled are asked for a code whatever this says.
  • mfaRequired - Whether every user who signs in must enroll in MFA. A user who is not enrolled gets a key that can only enroll. Requires mfaAvailable.
  • warnings - Warnings about the saved settings, returned on a change. Empty on a read.

These are set by environment variables, so they are read-only. A client uses them to decide which controls to offer. PATCH ignores them.

  • crossUserAccessEnabled - Whether administrators may use owner and all_users to reach other users' resources. Set by ADMIN_CROSS_USER_ACCESS_ENABLED. While it is off, those requests return 404 Not Found.
  • ledgerDeletionEnabled - Whether administrators may delete and purge ledger chains. Set by LEDGER_DELETION_ENABLED.
  • signingKeyExternallyManaged - Whether the output signing key is loaded from PHILTER_SIGNING_KEY_PATH. If so, POST /api/signing-key/regenerate returns 409 Conflict; replace the file instead.

Get the settings

GET /api/settings

Requires settings:read and an administrator.

Change settings

PATCH /api/settings

Requires settings:write and an administrator. Send only the settings to change; the rest are left as they are. Returns the settings as saved.

{
  "signingEnabled": true,
  "phieldEnabled": true,
  "phieldUrl": "https://phield.example.com",
  "phieldApiKey": "the Phield instance's PHIELD_API_KEY"
}
  • phieldApiKey - Sets the Phield API key. Leave it out to keep the current key; send "" to remove it.
  • phieldSourceId and phieldOrganization - Sending a blank value sets philter.

Values are validated before anything is saved. If any value is invalid, nothing is changed:

Status When
400 Bad Request A webhookAllowlist entry is not a hostname, an IP address, or a CIDR range; phieldUrl is not an absolute http or https URL; the request sends phieldEnabled or phieldUrl and Phield would end up enabled without a URL; or mfaRequired would be on while mfaAvailable is off. The body names the problem.
401 Unauthorized The Authorization header is absent or the API key is not recognized.
403 Forbidden The key does not hold the scope, or the caller is not an administrator. The message says which.

An http Phield URL with an API key is saved, and the response's warnings says the key will be sent in the clear.

curl -k -X PATCH "https://localhost:8080/api/settings" \
  -H "Authorization: Bearer <administrator key>" \
  -H "Content-Type: application/json" \
  --data '{"signingEnabled":true}'

Each instance caches the settings for up to ADMIN_SETTINGS_CACHE_TTL_SECONDS (see Settings). A change applies at once on the instance that made it, and on other instances when their cache expires.

Auditing

A change is recorded as a settings_updated audit event naming the settings that changed and the calling API key. Values are not recorded.

See also