GraphQL reference: user-management-settings
Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.
| Endpoint | https://<your-host>/api/user-management/settings/graphql |
| Auth plane | identity — Instance-scoped administration. Takes the identity token login returns BEFORE a tenant is selected, and is authorized for the superuser or an operator. A tenant access token is rejected here. |
| Authorize with | identity token |
| Schema file | /schema/user-management-settings.graphql |
| Described | 16 of 16 elements |
Queries
setting · settings · tokenMasks
setting
One setting by key. Fails with an "unknown setting key" error if no setting has that key; it does not return null. Requires settings:read.
Returns Setting
| Argument | Type | Description |
|---|---|---|
key | String! | Key of the setting, as listed by settings. |
settings
Every setting the instance defines, each with its value in effect. Requires settings:read.
Returns [Setting!]!
tokenMasks
The entity token masks as a JSON object serialized to a string: it maps an entity type
(or "default") to the mask template used to generate tokens for new entities of that
type. A template is literal text plus the placeholders {slug}, {uuid},
{alphanumeric-N} and {numeric-N}. It is the value of the entity.token_masks setting.
Unlike the other operations here it needs no settings authority, only a signed-in
caller, because every create form needs the masks. The same masks are served on the
tenant API.
Returns String!
Mutations
clearSetting
Removes a setting's override so the built-in default applies again, and returns the setting. Clearing a setting that has no override succeeds and changes nothing. The key must be one the instance defines, else it fails with an "unknown setting key" error. Requires settings:write.
Returns Setting!
| Argument | Type | Description |
|---|---|---|
key | String! | Key of the setting to reset. |
setSetting
Overrides a setting with a new value and returns the setting. The value must be valid JSON of at most 64 KiB and must satisfy the rules of that particular setting; otherwise the request fails and nothing changes. The key must be one the instance defines, else it fails with an "unknown setting key" error. Requires settings:write.
Returns Setting!
| Argument | Type | Description |
|---|---|---|
key | String! | Key of the setting to override. |
value | String! | The new value, as a JSON document serialized to a string. |
Objects
Setting
object
One instance-wide setting, with the value currently in effect and whether that value is an override or the built-in default.
| Field | Type | Description |
|---|---|---|
description | String! | What the setting controls and the shape its value must have. |
key | String! | Name of the setting, such as branding.default. Settings are identified by key. |
overridden | Boolean! | True when an override is stored and in effect; false when the built-in default is in use. |
updatedAt | String | When the override was last written, as an RFC 3339 timestamp. Null when the built-in default is in use. |
updatedBy | String | Email of the user who last wrote the override. Null when the built-in default is in use, or when the writer was not recorded. |
value | String! | The value in effect, as a JSON document serialized to a string: the override if one is set, otherwise the built-in default. |