Patch client-scoped settings.

PATCH

/api/admin/clients/{clientId}/settings

Code sample: Shell / cURL

curl --request PATCH \
  --url https://auth.example.com/api/admin/clients/example/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "ifMatch": "v1", "changes": { "oauth.require_pkce": true } }'

Update Setting in the Clients area. The request body is JSON unless the detailed schema for this operation states otherwise.

Authorizations

• adminBearer
• adminSessionCookie

Parameters

Path Parameters

clientId

required

string

Header Parameters

X-Tenant-Id

string

Tenant selector for multi-tenant admin requests.

Request Body ^required

Media type application/json

object

ifMatch

required

Expected settings version for optimistic concurrency.

string

set

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

login-ui.account_pages

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.

string

key

additional properties

clear

Array<string>

disable

Array<string>

key

additional properties

Example

{
  "ifMatch": "v1",
  "changes": {
    "oauth.require_pkce": true
  }
}

Responses

200

Settings v2 patch response.

Media type application/json

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

projection

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.

string

Allowed values: pending

externalPluginGate

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.

string

Allowed values: pending

key

additional properties

Example

{
  "applied": [
    "oauth.require_pkce"
  ],
  "cleared": [],
  "disabled": [],
  "rejected": {},
  "version": "v2"
}

503

The update could not be admitted or its completion could not be confirmed. Reload the current settings before retrying with their latest version.

Media type application/json

object

error

required

string

Allowed values: backup_mutation_unavailable

message

required

string

Example

{
  "error": "backup_mutation_unavailable"
}

Headers

Retry-After

string