Tenant Creation

Tenant Creation

Create and configure tenants in Mantis for multi-tenant deployments.

Overview

Tenants represent organizational units—customers, teams, or departments—that have isolated access to Mantis resources.

Note

All entity identifiers in Mantis are UUIDs. Readable placeholders such as solution_id: sol_webapp or environment_id: env_prod in the examples below stand in for real UUID values (for example 019b9450-0b91-8c10-86c3-5c2c3f6b9f04); substitute the actual UUIDs from your environment.

Creating a Tenant

Via API

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Acme Corp",
        "description": "Acme Corporation production tenant",
        "contact_email": "ops@acme.com",
        "logo_url": "https://acme.com/logo.png"
    }' \
    "https://api.mantis.local/api/v1/tenants"

Request Fields

Field	Required	Validation	Description
name	Yes	1-255 chars, unique	Tenant display name
description	No	None	Tenant description
contact_email	No	Valid email	Primary contact
logo_url	No	None	Branding logo URL

Response

{
  "id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
  "name": "Acme Corp",
  "description": "Acme Corporation production tenant",
  "contact_email": "ops@acme.com",
  "logo_url": "https://acme.com/logo.png",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": null
}

Via Lens UI

1. Navigate to Admin → Tenants
2. Click Create Tenant
3. Fill in the tenant form:
   • Name: Unique identifier for the tenant
   • Description: Optional details about the tenant
   • Contact Email: Primary contact for notifications
   • Logo URL: Optional branding image
4. Click Create

Attaching Solutions

After creating a tenant, grant access to solutions by attaching them with specific environments.

Via API

# Attach solution to tenant for a specific environment
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "solution_id": "019b937d-4862-8ccc-ddee-3344556677bb",
        "environment_id": "env_prod456"
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/solutions"

Solution-Environment Matrix

A tenant can have different solution access per environment:

# Grant access to WebApp in Production
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"solution_id": "sol_webapp", "environment_id": "env_prod"}' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/solutions"

# Grant access to WebApp in Staging
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"solution_id": "sol_webapp", "environment_id": "env_staging"}' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/solutions"

Via Lens UI

1. Navigate to Admin → Tenants → select tenant
2. Go to Solutions tab
3. Click Attach Solution
4. Select:
   • Solution: Choose from available solutions
   • Environment: Target environment for the entitlement
5. Click Attach

List Tenant Solutions

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/solutions"

Response:

[
  {
    "solution_id": "sol_webapp",
    "solution_name": "WebApp",
    "environment_id": "env_prod",
    "environment_name": "Production",
    "is_active": true
  },
  {
    "solution_id": "sol_webapp",
    "solution_name": "WebApp",
    "environment_id": "env_staging",
    "environment_name": "Staging",
    "is_active": true
  }
]

Detach Solution

curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/solutions/$SOLUTION_ID/environments/$ENV_ID"

Assigning Targets

Bind targets to tenants for deployment scope.

Via API

# Assign target to tenant (all environments)
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "target_id": "tgt_web01"
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets"

# Assign target to tenant for specific environment
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "target_id": "tgt_web02",
        "environment_id": "env_prod"
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets"

Target Scope

Scope	Configuration	Use Case
All environments	environment_id: null	Shared infrastructure
Single environment	environment_id: <env-uuid>	Dedicated production servers

Via Lens UI

1. Navigate to Admin → Tenants → select tenant
2. Go to Targets tab
3. Click Assign Target
4. Select:
   • Target: Choose from available targets
   • Environment: (Optional) Limit to specific environment
5. Click Assign

List Tenant Targets

# All targets
curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets"

# Filter by environment
curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets?environment_id=env_prod"

Remove Target Assignment

# Remove from specific environment
curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets/$TARGET_ID?environment_id=env_prod"

# Remove from all environments
curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/targets/$TARGET_ID"

Setting Variables

Configure tenant-specific variables for deployments.

Variable Types

Type	Key Format	Description
template	Template ID	Values for solution-defined templates
common	Free-form key	Custom key-value pairs

Set Template Variable

Template variables are defined by solutions and have values per tenant:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "variable_type": "template",
        "template_id_or_key": "tmpl_db_connection",
        "value": "postgresql://db.acme.local:5432/webapp",
        "environment_id": "env_prod",
        "is_encrypted": false
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/variables"

Set Common Variable

Common variables are free-form key-value pairs:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "variable_type": "common",
        "template_id_or_key": "custom_api_endpoint",
        "value": "https://api.acme.local/v2",
        "environment_id": null,
        "is_encrypted": false
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/variables"

Set Encrypted Variable

Sensitive values can be encrypted at rest:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "variable_type": "common",
        "template_id_or_key": "database_password",
        "value": "supersecret123",
        "is_encrypted": true
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/variables"

Variable Scope

Scope	Configuration	Behavior
Global	environment_id: null	Applies to all environments
Environment-specific	environment_id: <env-uuid>	Overrides global for that environment

List Variables

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/variables"

Response:

{
  "template_variables": [
    {
      "id": "019b937d-4862-8aaa-1111-000000000001",
      "tenant_id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
      "template_id": "019b937d-4862-8aaa-1111-000000000010",
      "template_name": "database_connection",
      "environment_id": "019b9450-0b91-8c10-86c3-5c2c3f6b9f04",
      "value": "postgresql://...",
      "is_encrypted": false,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "common_variables": [
    {
      "id": "019b937d-4862-8aaa-1111-000000000002",
      "tenant_id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
      "key": "custom_api_endpoint",
      "value": "https://api.acme.local/v2",
      "environment_id": null,
      "is_encrypted": false,
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}

Resolved Variables

Get final variable values with precedence applied:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/variables/resolved?solution_id=sol_webapp&environment_id=env_prod"

Adding Tags

Organize tenants with tags for filtering and grouping.

Attach Tags

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "tag_ids": ["tag_region_us", "tag_tier_enterprise"]
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/tags"

List Tags

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/tags"

Detach Tags

curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "tag_ids": ["tag_region_us"]
    }' \
    "https://api.mantis.local/api/v1/tenants/$TENANT_ID/tags"

Creating Tenant Users

After tenant creation, assign users to the tenant.

Via API

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "username": "alice",
        "email": "alice@acme.com",
        "password": "secure_password",
        "tenant_id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
        "role_ids": ["role_operator"]
    }' \
    "https://api.mantis.local/api/v1/admin/users"

Via SSO

Configure identity provider with tenant mapping:

1. Set up OIDC provider for the tenant
2. Configure role mappings
3. Users created on first SSO login are automatically tenant-scoped

See Identity Providers for SSO configuration.

Complete Setup Example

Full tenant onboarding script:

#!/bin/bash
set -e

API_URL="https://api.mantis.local/api/v1"
TOKEN="your-admin-token"

# 1. Create tenant
TENANT=$(curl -s -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Acme Corp",
        "description": "Enterprise customer",
        "contact_email": "ops@acme.com"
    }' \
    "$API_URL/tenants")

TENANT_ID=$(echo $TENANT | jq -r '.id')
echo "Created tenant: $TENANT_ID"

# 2. Attach solutions to environments
for ENV in "env_prod" "env_staging"; do
    curl -s -X POST \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"solution_id\": \"sol_webapp\", \"environment_id\": \"$ENV\"}" \
        "$API_URL/tenants/$TENANT_ID/solutions"
done
echo "Attached solutions"

# 3. Assign targets
for TARGET in "tgt_web01" "tgt_web02"; do
    curl -s -X POST \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"target_id\": \"$TARGET\"}" \
        "$API_URL/tenants/$TENANT_ID/targets"
done
echo "Assigned targets"

# 4. Set variables
curl -s -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "variable_type": "common",
        "template_id_or_key": "database_url",
        "value": "postgresql://db.acme.local:5432/webapp",
        "is_encrypted": false
    }' \
    "$API_URL/tenants/$TENANT_ID/variables"
echo "Set variables"

# 5. Add tags
curl -s -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"tag_ids": ["tag_enterprise", "tag_region_us"]}' \
    "$API_URL/tenants/$TENANT_ID/tags"
echo "Added tags"

echo "Tenant setup complete: $TENANT_ID"

Audit Trail

Tenant creation and modifications are logged:

{
  "event_type": "tenant.created",
  "event_category": "tenant_management",
  "severity": "info",
  "actor_type": "user",
  "actor_id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
  "actor_name": "admin",
  "resource_type": "tenant",
  "resource_id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
  "resource_name": "Acme Corp",
  "tenant_id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
  "action": "create",
  "outcome": "success",
  "occurred_at": "2024-02-01T10:00:00Z"
}

Troubleshooting

Tenant Name Conflict

Error: Tenant with name 'Acme Corp' already exists

Tenant names must be unique. Use a different name or include a suffix.

Solution Not Found

Error: Solution 019b937d-4862-8ccc-ddee-3344556677bb not found

Verify the solution exists before attaching to tenant.

Permission Denied

Error: Insufficient permissions

The response body contains error code INSUFFICIENT_PERMISSIONS. The required permission (tenants:create) appears in server-side audit logs. Assign the appropriate role to the user.

Next Steps

• Data Isolation - Understand security model
• Tenant Administration - Day-to-day management
• Users - Create tenant users