Patch client-scoped settings for a category.
curl --request PATCH \ --url https://auth.example.com/api/admin/clients/example/settings/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ifMatch": "v1", "changes": { "oauth.require_pkce": true } }'Partially updates client-scoped settings in a category. The request must include ifMatch; version conflicts return the current version. For the device-flow category the whole PATCH is refused (400 validation_failed, naming the key) when any key of it would be rejected one by one: an unknown key, a value of the wrong type, a fractional value where the setting is whole-number, a value outside its range, a key named by more than one of set, clear and disable, or any disable. Nothing is saved then. Relations are checked on the client’s resulting document, where every key the client does not set is the tenant’s value: min <= max for the expiry and interval bounds, device_flow.expires_in within the expiry bounds and device_flow.poll_interval within the interval bounds (so a client value outside the tenant’s bounds is refused). A cleared key counts as the value it then inherits (the tenant, the platform, an environment variable, else the default). A client min_* or max_* that would widen the tenant’s bounds is refused: a client can only narrow them. With the default device_flow.min_interval of 5, device_flow.poll_interval 2 is refused with 400. device_flow.user_code_charset and device_flow.user_code_length are tenant settings (the client is not known when a user types a code in): a client PATCH that names either is refused with 400.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Client identifier.
Settings category name that supports client scope.
Request Body required
Section titled “Request Body required ”object
Expected settings version for optimistic concurrency.
Setting keys and values to apply. For login-ui.primary_locales, use null for automatic defaults or an array of zero to six unique supported locale codes. The login-ui.show_english_language_names value must be boolean. The login-ui.account_pages value is a JSON-encoded Account Page document whose placements accept a boolean show_for_guests value; omission defaults guest visibility to true.
object
JSON-encoded authrim.account_pages.v1 document. Every screen placement may set show_for_guests to control whether its Account Page widget is rendered for guest accounts. The value defaults to true when omitted.
Example
{ "ifMatch": "v1", "changes": { "oauth.require_pkce": true }}Responses
Section titled “ Responses ”Settings v2 patch response.
Settings v2 patch result. Includes applied, cleared, disabled, rejected, and version metadata from the settings manager. A setting whose dependency (dependsOn) is met by an inherited value, the environment or the default is accepted; dependencies are checked against effective values, not only the values stored at the requested scope.
object
Present when the change was saved but could not yet be copied to the store runtime workers read. A scheduled retry copies it, normally within a minute; until then runtime keeps the previous values. Absent when the change already applies.
Only on a tenant plugin category save that touched plugin.enabled: the change was saved but ar-plugin-runner’s gate for external plugin code could not be put in step afterwards. After a turn-on the gate stays as it was (closed unless it had been opened before), so external code does not run on the strength of an unconfirmed “on”. After a turn-off the gate was closed before the save, but a concurrent enable may have reopened it. Either way saving plugin.enabled again, or enabling an external plugin, retries, and the periodic reconciliation puts the gate where the saved setting says within one pass. Absent when the gate is in step.
Example
{ "applied": [ "oauth.require_pkce" ], "cleared": [], "disabled": [], "rejected": {}, "version": "v2"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}The update could not be admitted or its completion could not be confirmed. Reload the current settings before retrying with their latest version.
object
Example
{ "error": "backup_mutation_unavailable"}