Settings

Configuration in Kontier lives at four levels, and the level a value lives at decides who it affects and when.

Deployment settings are not yours to change; they belong to whoever runs the installation. Everything else is.

Settings inherit down a ladder

✕

A setting is resolved down a ladder: the platform default, then the organization, then the workspace, then, for settings that records can carry, the entity (a customer, then a subscription). The lowest level that holds a value wins; a level that holds none follows the one above it.

Code
platform default  →  organization  →  workspace  →  customer  →  subscription

Each setting has a lowest level it can be set at. Some stop at the organization (they describe the company), most reach the workspace, and a few reach records. Organizations below yours in an organization tree inherit your values too, unless a setting is marked as local to one organization.

A level above can also constrain the levels below it: lock a setting so it cannot be overridden, or bound it so a lower level may only choose inside a range or an allowed set.

Where a saved value lands

• Saved from a live workspace, a value lands at the organization by default, so it inherits into every workspace, sandboxes included. Choose the workspace level explicitly for an override that governs only the workspace you are in.
• Saved from a sandbox, a value lands on that sandbox only. An experiment in sandbox never changes live, and a sandbox cannot write at organization level.

Removing a level's own value makes it follow the level above again, or the platform default when there is none above.

Entity settings follow the same ladder: many of them shadow a workspace default. That is covered in Entity settings.

Unknown keys are refused

The settings store validates every key against its catalog. A key it does not know is refused (400 VALIDATION, field code UNKNOWN_SETTING), and so is a value of the wrong type or outside its range (field code INVALID_VALUE), so a typo fails loudly rather than being saved and read by nothing.

Read and write settings over the API

API keys can read and write the keyed settings. Every write is validated against the settings catalog.

A PUT body groups values by type: settings for string, integer and boolean keys (each in its wire spelling, so "true" and "30" are strings), lists for list keys and amounts for money keys. level is organization or workspace and follows the rules in Where a saved value lands. To stop deciding a key at a level, DELETE it instead of sending an empty value.

Copy finance on every email from this workspace
curl -X PUT https://api.kontier.eu/v1/organization/settings \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "workspace",
    "lists": { "mail.house.cc": ["finance@acme.example"] }
  }'

To lock or bound a key for the levels below, send its value together with an entry under policies, for example "settings": {"security.sign_in.require_mfa": "true"}, "policies": {"security.sign_in.require_mfa": {"policy": "locked"}}. policy is default, bounded (with min/max, min_amount/max_amount or allowed) or locked. Leaving policies out keeps the policy a key already has; send default to lift a lock or bound.

What is organization-wide

Some things cannot differ between workspaces, because they describe the company rather than an environment:

• the company profile and tax identity
• security settings
• branding
• roles, members and invitations
• checkout links
• background job limits

Choosing a scope

When you are deciding where to configure something:

Where to go next