Tenant Variables

Scope variable values to a tenant so a solution deploys with tenant-specific configuration.

The model

Mantis has one variable entity, not separate “template” and “common” types. A variable holds a key, a value and a set of scopes it applies to — tenant, environment, target, solution and more. There is no per-tenant variable API; variables live in variable sets and are managed at /api/v1/variable-sets/{id}/variables, or under Deployment → Variable Sets in Lens.

A variable’s variable_type is one of string, sensitive (encrypted at rest), certificate or execution_pool. To make a value tenant-specific, set its scope_tenant_id.

Resolution: additive specificity

When a deployment needs a variable, every variable with that key whose scopes all match the deployment context is a candidate; any whose scope does not match is discarded. Each candidate’s score is the sum of the points for the scopes it carries, and the highest total wins (ties break on created_at, then id):

Scope	Points
Current action	1000
Current target	500
Target tags + action	400
Target tags	300
Tenant	200
Tenant tag	150
Environment	100
Channel	80
Solution	40
Variable set	20
Global (no scope)	0

Because scores accumulate, a variable scoped to tenant + environment (200 + 100 = 300) beats one scoped to the tenant alone (200) when both match. This is additive specificity, not an ordered override chain.

Example

For database_host, deploying solution customer-portal to tenant Acme in production:

Variable	Scopes	Matches?	Score
db.default	global	yes	0
db.acme.com	tenant=Acme	yes	200
db.acme-prod.com	tenant=Acme, env=production	yes	300
db.beta.com	tenant=Beta	no	discarded

db.acme-prod.com wins with 300.

Setting a tenant-scoped variable

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
        \"key\": \"database_host\",
        \"value\": \"db.acme.com\",
        \"variable_type\": \"string\",
        \"scope_tenant_id\": \"$TENANT_ID\"
    }" \
    "https://api.mantis.local/api/v1/variable-sets/$VARIABLE_SET_ID/variables"

For a secret, set "variable_type": "sensitive" — the value is encrypted at rest, and reads return "<ENCRYPTED>" rather than the plaintext.

Sensitive variables

sensitive variables are encrypted with the master key and never returned in clear. Rotate one by updating it with a new value; there is no separate rotation API.

Required variables

A deployment that references a variable with no matching candidate fails with Missing required prompted variables: <names>. Provide a global (unscoped) value as the fallback, since global matches every context at score 0.

Next Steps

• Multi-Tenancy Overview
• Variable Sets for the full variable-set workflow