Settings API key concepts

• Explanation
• Updated on Mar 26, 2026

The Settings API exposes a hierarchy of configuration objects organized by schema and scope. Before you start working with it at scale, be sure you understand how the API persists objects, how values flow through the scope hierarchy, and how the API handles concurrency, pagination, and access control.

Overview

Schemas define settings objects; scopes determine at what level a configuration applies. Each schema specifies the shape and constraints of a configuration type. The API provides distinct read endpoints depending on whether you need explicitly persisted values or the values currently in effect.

Schemas

Relevant endpoints: List schemas, View a schema

A schema defines the structure of a settings object: its properties, their types and constraints, and behavioral attributes such as multiObject, ordered, and maxObjects. Every settings object you read or write refers to a schema by its schemaId.

The schemaId you retrieve from the schema endpoints is what you pass as the schemaId parameter when reading or writing objects with List objects, Create an object, and the other object endpoints.

Persisted objects vs. effective values

The API exposes two distinct views of settings data:

Use List objects when you need to manage or audit configuration state. Use View effective values when you need the value that is actually in effect for a given scope.

Single-value vs. multi-value schemas

Settings schemas come in two flavors, controlled by the multiObject property on the schema definition:

Scopes

Every settings object targets exactly one scope, which you set via the scope field on creation. The scopes filter on List objects matches only objects that directly target the specified scope; it does not traverse the hierarchy. For example, filtering by environment will not return objects scoped to a host within that environment.

External IDs

Relevant endpoints: Create an object (request body), List objects (externalIds query parameter)

The externalId field lets you assign a stable, caller-defined identifier to a settings object at creation time (maximum 500 characters). This enables an upsert pattern: if an object with the given externalId already exists on the target scope, the request replaces it rather than creating a duplicate. You can also look up objects by their external IDs using the externalIds parameter on List objects.

Optimistic locking

Relevant endpoints: List objects, View an object, Edit an object, Delete an object

The updateToken field is a concurrency control mechanism. The API generates and returns it with every retrieval request. Including it on a subsequent update or delete means the operation only proceeds if the object hasn't changed since you last fetched it; if it has changed, the API rejects the request so you can reconcile the conflict.

Omitting updateToken on a write or delete bypasses this check and unconditionally applies the change.

Pagination

Relevant endpoints: List objects, View effective values

All list endpoints use cursor-based pagination via nextPageKey. The cursor appears in the response when more pages exist; pass it as the nextPageKey query parameter to fetch the next page.

Important: when nextPageKey is set, all other query parameters must be omitted. Filters, schema IDs, scopes, and field projections apply only to the first-page request and encode into the cursor for subsequent pages.

Batch writes

Create an object accepts an array of objects in a single request. The API processes each object in the batch independently and returns its own HTTP status code in the response body; check per-item codes rather than relying on the top-level response status. A partially failed batch does not roll back successful items.

Sparse fieldsets (fields parameter)

The fields query parameter lets you limit which top-level fields are returned in a response. When provided, it replaces the default field set entirely—it is not additive. If you specify fields=objectId,value, you will get only those two fields; any other fields from the default set (such as scope or schemaId) are excluded.

Responses don't include updateToken by default. If you need it for optimistic locking, request it explicitly: fields=objectId,value,scope,updateToken.

Secret-type properties

Relevant endpoint: Edit an object

The API masks properties of type secret in GET responses. On PUT, you can either send the plaintext value to update a secret, or send back the masked value to keep it unchanged—unless the schema restricts this for specific non-secret properties.

Some non-secret property definitions carry a forceSecretResubmission field. When forceSecretResubmission: true, you cannot update that non-secret property while keeping secrets masked — the API requires you to provide plaintext values for all secret properties in the same schema alongside that change.

This restriction closes a potential exfiltration vector. Consider a schema that stores both a secret (for example, an API key) and a destination URL. Without forceSecretResubmission: true on the URL property, an attacker with write access could change only the URL to a server they control while leaving the secrets masked—the server would silently re-use the stored plaintext the next time it called the API, forwarding the credential to the attacker. By requiring secret resubmission when the URL changes, the schema ensures the caller already knows the secrets before they can submit a valid update.

For non-secret properties where forceSecretResubmission is absent or false, you can update them freely while sending back masked values for secret properties. To check whether a specific non-secret property carries this restriction, inspect its definition in the schema.

Dry-run validation (validateOnly)

Relevant endpoints: Create an object, Edit an object

Setting validateOnly=true runs the full server-side validation of the submitted objects without persisting anything. Use this to verify payload correctness before committing a write, particularly when working with unfamiliar schemas.

Owner-based access control

Relevant endpoints: List object permissions, Add accessor permission, Get accessor permission, Update accessor permission, Delete accessor permission, Get all-users permission, Update all-users permission, Delete all-users permission, Transfer ownership

Some schemas enable owner-based access control. You can identify them by including ownerBasedAccessControl in the add-fields parameter when calling List schemas, that are the schemas with ownerBasedAccessControl: true in the response use this model. For objects under such schemas, the creator becomes the owner and the object is private by default; no other user or group has access until the owner explicitly grants it. The owner manages fine-grained permissions via the /settings/objects/{objectId}/permissions sub-resource. The sub-resource supports two accessor types:

Any user who holds read and write object-level permissions can add or update permissions on the object. Only the current owner or a user with the settings:objects:admin permission (globally or for the relevant schema) can transfer ownership. When ownership transfers, the previous owner loses access unless they are explicitly listed as an accessor on the object.

The adminAccess query parameter, available on nearly all endpoints, allows you to bypass ownership restrictions and act as the effective owner of any object if you have the settings:objects:admin permission. Note that settings:objects:admin does not grant read or write access to settings objects — you must still hold the appropriate settings:objects:read or settings:objects:write permission for the operation to succeed.

Use cases