Skip to main content

Tenant Setup Guide

This guide provides step-by-step instructions for configuring tenants in the Inference API platform. The platform supports multi-tenancy with complete data isolation, where each tenant has its own MongoDB database and Redis instance.

Table of Contents​

  1. Prerequisites
  2. Understanding Tenant Configuration
  3. Configuration Parameters
  4. Setup Steps
  5. Configuration Examples
  6. Database Setup
  7. Testing the Configuration
  8. Troubleshooting
  9. Security Best Practices

Prerequisites​

Before setting up a tenant, ensure you have:

  1. Database Access: Access to MongoDB and Redis instances for the tenant
  2. Network Access: The platform must be able to reach tenant database instances
  3. Platform Access: Access to configure environment variables or tenant settings
  4. Unique Tenant ID: A unique identifier for the tenant (alphanumeric, underscores, hyphens)
  5. Frontend URL: The URL of your frontend application (for OIDC redirects if using SSO)

Understanding Tenant Configuration​

The Inference API platform uses a multi-tenant architecture where each tenant has:

  • Isolated MongoDB Database: Each tenant has its own MongoDB database
  • Isolated Redis Instance: Each tenant has its own Redis database number
  • Independent Configuration: Each tenant can have its own OIDC settings, frontend URL, etc.
  • Complete Data Isolation: Tenants cannot access each other's data

Tenant Context Resolution​

The platform resolves tenant context from requests in the following order:

  1. JWT Token: Contains tenant_id claim in the token payload
  2. API Key: Tenant ID is embedded in the API key format ({tenant_id}_sk_...)
  3. Request Header: Fallback via x-tenant-id header (if supported)

Connection Management​

  • MongoDB: Connection pool per tenant, established at application startup
  • Redis: Client instance per tenant, established at application startup
  • Startup: All tenant connections are initialized during application initialization
  • Health Checks: Per-tenant connection monitoring

Configuration Parameters​

The tenant configuration includes the following parameters:

ParameterDescriptionRequiredExample
tenant_idUnique identifier for the tenantYesacme_corp
nameHuman-readable tenant nameYesAcme Corporation
mongo_uriMongoDB connection stringYesmongodb://localhost:27017
mongo_databaseMongoDB database name for this tenantYesacme_corp_db
redis_addrRedis server address (host:port)Yeslocalhost:6379
redis_dbRedis database number (0-15)Yes0
frontend_urlFrontend application URLNohttps://app.acme.com
oidc_issuerOIDC provider issuer URLNo*https://login.microsoftonline.com/{tenant}/v2.0
oidc_client_idOIDC client IDNo*00001111-aaaa-2222-bbbb-3333cccc4444
oidc_client_secretOIDC client secretNo*your-secret-value
oidc_redirect_urlOIDC callback URLNo*https://api.yourplatform.com/v1/auth/oidc/callback
oidc_scopesOIDC scopes (space-separated)Noopenid profile email

* Required if oidc_issuer is provided. See OIDC Setup Guide for OIDC configuration details.

Parameter Validation​

The platform validates tenant configuration as follows:

  1. Required Fields: tenant_id, name, mongo_uri, mongo_database, and redis_addr must be provided
  2. OIDC Configuration: If oidc_issuer is provided, oidc_client_id, oidc_client_secret, and oidc_redirect_url are required
  3. Default OIDC Scopes: If oidc_scopes is not provided but OIDC is configured, defaults to "openid profile email"
  4. Unique Tenant IDs: Each tenant must have a unique tenant_id

Setup Steps​

Step 1: Prepare Database Infrastructure​

  1. MongoDB Setup:

    • Create or identify a MongoDB instance for the tenant
    • Ensure the database is accessible from the platform
    • Note the connection string (e.g., mongodb://host:port or mongodb://user:password@host:port/database)
    • Choose a unique database name for the tenant

  2. Redis Setup:

    • Create or identify a Redis instance for the tenant
    • Ensure Redis is accessible from the platform
    • Choose a unique Redis database number (0-15) for the tenant
    • Note the Redis address (host:port)

Step 2: Create Tenant Configuration​

Create a JSON configuration object for your tenant:

{
  "tenant_id": "acme_corp",
  "name": "Acme Corporation",
  "mongo_uri": "mongodb://acme-mongo:27017",
  "mongo_database": "acme_corp_db",
  "redis_addr": "acme-redis:6379",
  "redis_db": 0,
  "frontend_url": "https://app.acme.com"
}

Step 3: Configure Environment Variables​

The platform reads tenant configurations from the TENANT_CONFIGS environment variable, which should contain a JSON array of tenant configurations.

Single Tenant Example​

export TENANT_CONFIGS='[
  {
    "tenant_id": "acme_corp",
    "name": "Acme Corporation",
    "mongo_uri": "mongodb://acme-mongo:27017",
    "mongo_database": "acme_corp_db",
    "redis_addr": "acme-redis:6379",
    "redis_db": 0,
    "frontend_url": "https://app.acme.com"
  }
]'

Multiple Tenants Example​

export TENANT_CONFIGS='[
  {
    "tenant_id": "acme_corp",
    "name": "Acme Corporation",
    "mongo_uri": "mongodb://acme-mongo:27017",
    "mongo_database": "acme_corp_db",
    "redis_addr": "acme-redis:6379",
    "redis_db": 0,
    "frontend_url": "https://app.acme.com"
  },
  {
    "tenant_id": "globex_inc",
    "name": "Globex Inc",
    "mongo_uri": "mongodb://globex-mongo:27017",
    "mongo_database": "globex_inc_db",
    "redis_addr": "globex-redis:6379",
    "redis_db": 1,
    "frontend_url": "https://app.globex.com"
  }
]'

Step 4: Set Default Tenant (Optional)​

If you have multiple tenants, you can specify a default tenant:

export DEFAULT_TENANT_ID="acme_corp"

If DEFAULT_TENANT_ID is not set and you have multiple tenants, the platform will use the first tenant in the configuration array as the default.

Step 5: Configure OIDC (Optional)​

If you want to enable OIDC authentication for the tenant, add OIDC configuration parameters:

{
  "tenant_id": "acme_corp",
  "name": "Acme Corporation",
  "mongo_uri": "mongodb://acme-mongo:27017",
  "mongo_database": "acme_corp_db",
  "redis_addr": "acme-redis:6379",
  "redis_db": 0,
  "frontend_url": "https://app.acme.com",
  "oidc_issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "oidc_client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "oidc_client_secret": "your-client-secret",
  "oidc_redirect_url": "https://api.yourplatform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

See the OIDC Setup Guide for detailed OIDC configuration instructions.

Step 6: Start the Platform​

  1. Verify Configuration: Ensure all environment variables are set correctly
  2. Start the Service: Start the Inference API service
  3. Check Logs: Verify that tenant connections are established successfully
  4. Verify Health: Check that all tenant databases are accessible

Configuration Examples​

Example 1: Basic Tenant (No OIDC)​

{
  "tenant_id": "demo_tenant",
  "name": "Demo Tenant",
  "mongo_uri": "mongodb://localhost:27017",
  "mongo_database": "demo_db",
  "redis_addr": "localhost:6379",
  "redis_db": 0,
  "frontend_url": "https://demo.example.com"
}

Example 2: Tenant with OIDC (Microsoft Entra ID)​

{
  "tenant_id": "enterprise_tenant",
  "name": "Enterprise Tenant",
  "mongo_uri": "mongodb://enterprise-mongo:27017",
  "mongo_database": "enterprise_db",
  "redis_addr": "enterprise-redis:6379",
  "redis_db": 0,
  "frontend_url": "https://app.enterprise.com",
  "oidc_issuer": "https://login.microsoftonline.com/abc123/v2.0",
  "oidc_client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "oidc_client_secret": "enterprise-secret-value",
  "oidc_redirect_url": "https://api.platform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Example 3: Tenant with OIDC (Keycloak)​

{
  "tenant_id": "keycloak_tenant",
  "name": "Keycloak Tenant",
  "mongo_uri": "mongodb://keycloak-mongo:27017",
  "mongo_database": "keycloak_db",
  "redis_addr": "keycloak-redis:6379",
  "redis_db": 0,
  "frontend_url": "https://app.keycloak.com",
  "oidc_issuer": "https://keycloak.example.com/realms/my-realm",
  "oidc_client_id": "inference-api-client",
  "oidc_client_secret": "keycloak-secret",
  "oidc_redirect_url": "https://api.platform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Example 4: Docker Compose Environment​

services:
  inference-api:
    environment:
      TENANT_CONFIGS: |
        [
          {
            "tenant_id": "acme_corp",
            "name": "Acme Corporation",
            "mongo_uri": "mongodb://mongodb:27017",
            "mongo_database": "acme_corp_db",
            "redis_addr": "redis:6379",
            "redis_db": 0,
            "frontend_url": "https://app.acme.com"
          }
        ]
      DEFAULT_TENANT_ID: "acme_corp"

Database Setup​

MongoDB Setup​

  1. Create Database: The platform will automatically create the database if it doesn't exist
  2. Indexes: The platform automatically creates required indexes on startup
  3. Connection String Formats:
    • Basic: mongodb://host:port
    • With Authentication: mongodb://username:password@host:port
    • With Database: mongodb://host:port/database
    • Replica Set: mongodb://host1:port1,host2:port2/?replicaSet=rs0
    • SSL: mongodb://host:port/?ssl=true

Redis Setup​

  1. Database Number: Choose a unique Redis database number (0-15) for each tenant
  2. Connection: Ensure Redis is accessible from the platform
  3. Persistence: Configure Redis persistence based on your requirements
  4. Memory: Allocate appropriate memory for each tenant's Redis instance

Testing the Configuration​

Step 1: Verify Configuration Loading​

  1. Check Startup Logs: Look for tenant initialization messages:

    Initializing tenant: acme_corp
    MongoDB client created for tenant: acme_corp
    Redis client created for tenant: acme_corp

  2. Verify Connections: Check that all tenant connections are established without errors

Step 2: Test Database Access​

  1. MongoDB Connection: Verify MongoDB connection:

    # Test MongoDB connection from platform host
    mongosh "mongodb://acme-mongo:27017"

  2. Redis Connection: Verify Redis connection:

    # Test Redis connection from platform host
    redis-cli -h acme-redis -p 6379 -n 0 PING

Step 3: Test API Access​

  1. Create API Key: Create an API key for the tenant (tenant ID will be embedded in the key)

  2. Test Request: Make a test API request:

    curl -X GET https://api.yourplatform.com/v1/some-endpoint \
      -H "x-api-key: {tenant_id}_sk_..."

  3. Verify Tenant Context: Check that the request is routed to the correct tenant's database

Step 4: Test OIDC (If Configured)​

  1. Initiate Login: Test OIDC login flow:

    curl -X POST https://api.yourplatform.com/v1/auth/oidc/login \
      -H "Content-Type: application/json" \
      -d '{"tenant_id": "acme_corp"}'

  2. Verify Redirect: Ensure you're redirected to the correct OIDC provider

  3. Complete Flow: Complete authentication and verify token delivery

Security Best Practices​

Tenant Isolation​

  1. Separate Databases: Use completely separate MongoDB databases for each tenant
  2. Separate Redis Instances: Use different Redis database numbers or separate instances
  3. Network Isolation: Consider network-level isolation for sensitive tenants
  4. Access Control: Implement proper access controls at the database level

Configuration Security​

  1. Secrets Management: Store sensitive values (OIDC secrets, database passwords) in secure secret management systems
  2. Environment Variables: Use environment variables or secret management tools, not hardcoded values
  3. Encryption: Encrypt sensitive configuration data at rest
  4. Access Control: Limit access to tenant configuration to authorized personnel only

API Key Security​

  1. Tenant-Scoped Keys: API keys are automatically scoped to tenants and cannot cross tenant boundaries
  2. Key Rotation: Implement regular API key rotation policies
  3. Key Storage: Store API keys securely and never expose them in logs or error messages

Database Security​

  1. Authentication: Use MongoDB authentication for all connections
  2. Encryption: Enable TLS/SSL for MongoDB and Redis connections
  3. Network Security: Use firewalls and network policies to restrict database access
  4. Backup: Implement regular backups for each tenant's database

Monitoring and Auditing​

  1. Tenant-Aware Logging: Ensure all logs include tenant context
  2. Audit Trails: Track tenant data access and modifications
  3. Monitoring: Monitor per-tenant resource usage and performance
  4. Alerting: Set up alerts for tenant-specific issues

Additional Resources​