Patch platform-scoped settings for a category.
curl --request PATCH \ --url https://auth.example.com/api/admin/platform/settings/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ifMatch": "example", "set": { "login-ui.account_pages": "example" }, "clear": [ "example" ], "disable": [ "example" ] }'Update Setting settings in the Admin Miscellaneous area. The request body is JSON unless the detailed schema for this operation states otherwise. The category must be available at the platform scope and writable, and the caller needs platform authority from a global role assignment (an administrator limited to one tenant is refused with 403, whatever role it holds there), or, for a machine token, the settings write permission with a global tenant scope (a token limited to some tenants is refused with 403). For the identity-mapping category, identity_mapping.oidc_default_set_id (the default for every tenant that has set no default of its own, and has not saved none) names the Mapping Set that applies to apps of the scope that choose none of their own (unset: no default, so no mapping applies; there is no environment variable; apps that choose none of their own use it for the ID token, UserInfo and the consent screen, and a value that cannot be used stops them from signing in). The value is a Mapping Set ID (letters, digits and _ . : -, at most 200 characters, no surrounding whitespace) or, for a tenant, the reserved value none, which refuses the platform’s default; a string only (the disabled marker, false and null are refused, and disable is refused for the key; clear it to remove it). The set must exist and be usable, or the whole PATCH is refused with 400 validation_failed and nothing is saved: a tenant may name a set it owns or one the platform owns, the platform only one the platform owns (any other set answers the same as one that does not exist); the set must be active, with an active activation that applies to the tenant (or to every tenant) and an active compiled snapshot, and must release into exactly one active OIDC Destination Profile; a platform-owned set must also hold only what a platform set may hold. 503 temporarily_unavailable when the Admin database cannot be read to check it (nothing is saved). The category is not available for apps (400), and cannot be rolled back through the settings history routes (400). The category also holds platform-only limits of the search for what names a Mapping Set (identity_mapping.reference_scan_tenant_limit 1 to 1000, reference_scan_row_limit 10 to 5000, reference_scan_concurrency 1 to 16 and reference_display_limit 1 to 100, whole numbers; defaults 200, 500, 8 and 20; a value outside the range is refused with 400 on the platform and is not accepted for a tenant). A value in the environment or the store that is outside the range is ignored and the default is used.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Header Parameters
Section titled “Header Parameters ”Tenant selector for multi-tenant admin requests.
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.
Accepted only for the identity-mapping category at platform scope. expected_version is an alias for ifMatch; when both are present they must be nonempty identical strings. Other categories reject these new guards. expected_following requires a set or clear operation for identity_mapping.oidc_default_set_id. The server re-reads the complete tenant relation inventory immediately before applying the existing settings CAS. A count mismatch returns 409, an incomplete read or exceeded budget returns 503, and malformed guards return 400. These failures do not change the settings document or its runtime projection. The count check is point-in-time and does not establish an atomic snapshot across tenant databases.
object
object
Accepted only for the identity-mapping category at platform scope. expected_version is an alias for ifMatch; when both are present they must be nonempty identical strings. Other categories reject these new guards. expected_following requires a set or clear operation for identity_mapping.oidc_default_set_id. The server re-reads the complete tenant relation inventory immediately before applying the existing settings CAS. A count mismatch returns 409, an incomplete read or exceeded budget returns 503, and malformed guards return 400. These failures do not change the settings document or its runtime projection. The count check is point-in-time and does not establish an atomic snapshot across tenant databases.
object
object
Example generated
{ "ifMatch": "example", "set": { "login-ui.account_pages": "example" }, "clear": [ "example" ], "disable": [ "example" ]}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"}The settings changed since ifMatch or expected_version, or the number of tenants following the platform default differs from expected_following. Reload the settings and repeat the preview before retrying.
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"}