One company wants an alert at 10 units, another at 50. One wants emails on, another off. Settings let each workspace tune your module without anyone touching its code, and without you shipping a new version for every preference.
Where people find them
Module Settings opens from the ⋮ button next to your module in the sidebar. It shows only to Workspace Admins and to people whose role has your module's MANAGE_SETTINGS permission.
| Tab | What's on it | Shows when |
|---|---|---|
| Configuration | Your module's own settings screen | Your module ships one |
| Messages | The wording of the emails your module sends | Your module sends email |
| Preferences | The platform's settings editor, your public pages, and version history | Always |
Workspace settings and platform settings
Workspace settings are the ones each workspace may change. You declare each one with a type, a default and a plain description:
| Type | Shows as | Example |
|---|---|---|
| Yes / no | A checkbox (Enabled / Disabled) | Email the customer when a job closes |
| Whole number | A number box | Low stock alert at 10 |
| Text | A text box | Default job prefix JOB- |
A text setting for an AI model shows a model picker instead, with Module default at the top.
Platform settings are values you set for every workspace. Mark one locked and it wins over anything a workspace sets; workspaces can see it but not change it.
Your module reads the current values whenever it needs them, falling back to your default when nobody changed it. Changes reach the module within about 15 seconds.
Secrets
Is it an API key or a password for an outside service? Mark the setting secret. It then always shows masked (********) with "is set", even to admins, and only your module's server code reads the real value. Settings named like a credential (password, api_key, token) are treated as secret automatically.
Public settings
A few harmless values, like a company tagline on a careers page, can be marked public so a page can read them before anyone signs in. Credential-like settings can never be public.
Your own settings screen
The standard editor handles yes/no, numbers and text. Anything richer, like a list of job types, a price table or a template, deserves its own screen. Ship one in your module and it appears as the Configuration tab, already signed in as the person, in the workspace's colours.
Ask the Module Builder
// For developers: module.json
"tenant_settings": [
{"key": "low_stock_alert", "type": "integer", "default": 10,
"description": "Warn when stock falls to this many units"},
{"key": "supplier_api_key", "type": "string", "default": "", "secret": true,
"description": "Your supplier portal key"}
],
"ui": {"tenant_settings_page": true}Good to know
- Settings are included. No charge for reading or saving them.
- Secrets are stored with the workspace's subscription, not in a vault. If one is ever exposed, change it at the provider.
- Version history is on Preferences too. A Workspace Admin can see each version of your module the workspace has run, and roll back if needed. See Module settings and versions.
- Email wording lives on the Messages tab. See Email.
- Who may open Module Settings follows your MANAGE_SETTINGS permission. See Users, roles and permissions in your module.