Tenant Variables

Configure tenant-specific values for deployments.

Variable Types

Mantis supports two types of tenant variables:

Type	Description	Scope
Template Variables	Values for solution-defined templates	Per solution
Common Variables	Key-value pairs shared across solutions	Global to tenant

Template Variables

What Are Template Variables?

Solutions define variable templates that tenants must fill in:

Template Properties

Property	Description
Name	Variable identifier (e.g., database_host)
Label	Human-readable name
Help Text	Usage instructions
Control Type	Input type for UI
Default Value	Pre-filled value if not set
Required	Must be set before deployment

Control Types

Type	Description	Use Case
Text	Single-line input	URLs, hostnames
Multiline	Multi-line text area	Configuration blocks
Select	Dropdown selection	Predefined options
Checkbox	Boolean toggle	Feature flags
Sensitive	Password input (encrypted)	API keys, secrets

Setting Template Variables

┌─────────────────────────────────────────────────────────────┐
│  Tenant Variables: Acme Corp                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Solution: customer-portal                                  │
│  Environment: [All         ▼]                               │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  database_host *                                            │
│  Database server hostname                                   │
│  [db.acme.com                               ]               │
│                                                             │
│  api_key *                                                  │
│  External API key (encrypted)                               │
│  [••••••••••••••••••                        ]               │
│                                                             │
│  log_level                                                  │
│  Application log verbosity                                  │
│  [info              ▼]                                      │
│    debug                                                    │
│    info                                                     │
│    warn                                                     │
│    error                                                    │
│                                                             │
│  feature_new_checkout                                       │
│  Enable new checkout experience                             │
│  [✓]                                                        │
│                                                             │
│                                     [Cancel]  [Save]        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

* Required field

Environment-Specific Values

Variables can be set globally or per environment:

┌─────────────────────────────────────────────────────────────┐
│  Variable: database_host                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────┬────────────────────────────────────────┐│
│  │ Environment   │ Value                                  ││
│  ├───────────────┼────────────────────────────────────────┤│
│  │ (Default)     │ db.acme.com                            ││
│  │ Development   │ dev-db.acme.local                      ││
│  │ Staging       │ staging-db.acme.com                    ││
│  │ Production    │ prod-db.acme.com                       ││
│  └───────────────┴────────────────────────────────────────┘│
│                                                             │
└─────────────────────────────────────────────────────────────┘

Common Variables

What Are Common Variables?

Key-value pairs available across all solutions:

Tenant: Acme Corp
Common Variables:
├── company_name = "Acme Corporation"
├── support_email = "support@acme.com"
├── region_code = "us-east-1"
└── ssl_enabled = "true"

Creating Common Variables

┌─────────────────────────────────────────────────────────────┐
│  Common Variables: Acme Corp                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┬──────────────────┬───────┬───────────┐ │
│  │ Key            │ Value            │ Scope │ Actions   │ │
│  ├────────────────┼──────────────────┼───────┼───────────┤ │
│  │ company_name   │ Acme Corporation │ All   │ [Edit][×] │ │
│  │ support_email  │ support@acme.com │ All   │ [Edit][×] │ │
│  │ region_code    │ us-east-1        │ Prod  │ [Edit][×] │ │
│  └────────────────┴──────────────────┴───────┴───────────┘ │
│                                                             │
│  [+ Add Variable]                                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via Lens / REST API

Tenant variables are managed in Lens or through the /api/v1/tenants/<tenant-id>/variables REST endpoints (there is no mantisctl variable subcommand). To set a tenant-scoped variable:

# Set a tenant variable (variable_type is "common" or "template")
curl -X POST "$MANTIS_URL/api/v1/tenants/<tenant-id>/variables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id_or_key": "company_name", "value": "Acme Corporation", "variable_type": "common", "is_encrypted": false}'

# List a tenant's variables
curl "$MANTIS_URL/api/v1/tenants/<tenant-id>/variables" \
  -H "Authorization: Bearer $TOKEN"

/api/v1/variable-sets is a separate feature for reusable library variable sets linked to solutions — not tenant variables.

Variable Resolution

Resolution Order

Variables are resolved in this order (later overrides earlier):

Example Resolution

Variable: database_host
Deployment: customer-portal to Acme Corp (Production)

Resolution:
1. Solution default:     "localhost"
2. Common (no env):      "db.acme.com"
3. Common (Production):  (not set)
4. Template (no env):    "db.acme.com"
5. Template (Production):"prod-db.acme.com"

Final value: "prod-db.acme.com"

Sensitive Variables

Encryption

Variables marked as sensitive are encrypted at rest:

┌─────────────────────────────────────────────────────────────┐
│  Sensitive Variable                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  api_key                                                    │
│  [••••••••••••••••••                        ]               │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 🔒 This value is encrypted at rest.                  │  │
│  │ Write-only — it cannot be retrieved after saving.    │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Setting Sensitive Variables

Mark a variable sensitive by setting its variable_type to sensitive. The stored value is encrypted at rest and masked in responses:

curl -X POST "$MANTIS_URL/api/v1/variable-sets/<set-id>/variables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_key",
    "value": "secret-key-123",
    "variable_type": "sensitive"
  }'

Security Considerations

Practice	Description
Use sensitive flag	Always encrypt secrets
Rotate regularly	Update sensitive values periodically
Audit access	Review who can view sensitive variables
Avoid in scripts	Don’t hardcode sensitive values

Variable Substitution

In Deployment Scripts

Variables are available in scripts:

deploy.sh

#!/bin/bash
echo "Deploying to ${database_host}"
echo "API Key configured: ${api_key:+yes}"

# Use variables in configuration
cat > /app/config.json << EOF
{
  "database": "${database_host}",
  "logLevel": "${log_level:-info}",
  "features": {
    "newCheckout": ${feature_new_checkout:-false}
  }
}
EOF

Variable Syntax

Syntax	Description	Example
${var}	Simple substitution	${database_host}
${var:-default}	Default if unset	${log_level:-info}
${var:+alt}	Alternate if set	${api_key:+configured}

Managing Variables

Bulk Import

There is no single bulk-import command. To load many variables, iterate over a file and POST each one to the variable set:

# variables.json
{
  "database_host": "db.acme.com",
  "api_key": "secret-key",
  "log_level": "info"
}

# Import each entry into a variable set
jq -r 'to_entries[] | "\(.key)\t\(.value)"' variables.json | \
while IFS=$'\t' read -r key value; do
  curl -s -X POST "$MANTIS_URL/api/v1/variable-sets/<set-id>/variables" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"$key\", \"value\": \"$value\"}"
done

Bulk Export

List a variable set’s variables and reshape the JSON for backup or migration (sensitive values are masked in the response):

curl -s "$MANTIS_URL/api/v1/variable-sets/<set-id>/variables" \
  -H "Authorization: Bearer $TOKEN" > variables-backup.json

Variable History

Per-variable change history is not tracked in a dedicated view. To see who changed a variable and when, use the audit log (/api/v1/audit), which records variable create, update, and delete events.

Validation

Required Variables

Deployments are blocked if required variables are missing:

┌─────────────────────────────────────────────────────────────┐
│  Deployment Blocked                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Cannot deploy: Missing required variables                  │
│                                                             │
│  ✗ database_host - Not set for Production                   │
│  ✗ api_key - Not set                                        │
│                                                             │
│  Set these variables before deploying.                      │
│                                                             │
│                        [Set Variables]  [Cancel]            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Pre-Deployment Check

View resolved variables before deployment:

┌─────────────────────────────────────────────────────────────┐
│  Resolved Variables                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Deployment: customer-portal v1.4.0 to Production           │
│  Tenant: Acme Corp                                          │
│                                                             │
│  ┌────────────────┬────────────────────┬───────────────┐   │
│  │ Variable       │ Value              │ Source        │   │
│  ├────────────────┼────────────────────┼───────────────┤   │
│  │ database_host  │ prod-db.acme.com   │ Template/Prod │   │
│  │ api_key        │ ••••••             │ Template      │   │
│  │ log_level      │ warn               │ Template/Prod │   │
│  │ company_name   │ Acme Corporation   │ Common        │   │
│  └────────────────┴────────────────────┴───────────────┘   │
│                                                             │
│                           [Back]  [Deploy]                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Best Practices

1. Organize Variables Logically

Category	Variables
Connection	database_host, redis_url, api_endpoint
Credentials	api_key, db_password, ssl_cert
Configuration	log_level, timeout, max_retries
Feature Flags	feature_x, enable_beta

2. Use Defaults Wisely

Set sensible defaults in templates:

Variable	Good Default	Why
log_level	info	Safe for production
timeout_seconds	30	Reasonable wait
max_retries	3	Standard retry count
api_key	(none)	Must be explicitly set

3. Document Variables

Add help text to templates:

Variable: database_host
Label: Database Host
Help Text: "PostgreSQL server hostname (e.g., db.company.com)"

4. Review Before Production

Always verify variables before production deployments:

• Check all required variables are set
• Verify environment-specific overrides
• Confirm sensitive values are current

Troubleshooting

Variable Not Being Used

Cause: Wrong variable name or scope

Solution:

1. Check exact variable name (case-sensitive)
2. Verify environment scope matches deployment
3. Check resolution order

Sensitive Variable Shows as Empty

Cause: Encryption key issue or not set

Solution:

1. Re-set the sensitive variable
2. Check encryption configuration
3. Contact administrator if persists

Deployment Fails on Variable Substitution

Cause: Invalid variable reference in script

Solution:

1. Check syntax (${var} not $var)
2. Verify variable exists
3. Add default value: ${var:-default}

Next Steps

• Switching Tenants - Change tenant context
• Tenant Context - Working in tenant scope
• Overview - Return to tenants overview