Tenant Management

Guide to multi-tenant setup and management.

Overview

WalletPass.ai uses a Silo Multi-Tenancy architecture where each tenant operates in complete isolation:

Database Schema - Dedicated PostgreSQL schema per tenant
API Keys - Unique, secure API keys for authentication
Data Isolation - Complete separation of data between tenants

Tenant Onboarding

Step 1: Create Bearer Token

Create a bearer token for tenant creation:

bash

curl -X POST https://tenant.walletpass.ai/v1/bearer-tokens \
  -H "Authorization: Bearer admin@walletpass.ai" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Token",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

json

{
  "status": "success",
  "data": {
    "id": "token-uuid",
    "token": "bt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "Development Token",
    "expires_at": "2026-12-31T23:59:59Z"
  }
}

Important: Save the token value - you'll need it to create tenants.

Step 3: Create Tenant

Use the bearer token to create a new tenant:

bash

curl -X POST https://tenant.walletpass.ai/v1/onboard \
  -H "Authorization: Bearer bt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Company"
  }'

Note: The client_name field is required. Contact information (contact_email, contact_name) is not currently stored but may be added in future versions.

Response:

json

{
  "status": "success",
  "message": "Tenant onboarded successfully",
  "data": {
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "api_key": "wp_xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "company_name": "My Company",
    "contact_email": "contact@mycompany.com",
    "created_at": "2025-01-09T10:30:00Z"
  }
}

Important: Save the api_key - this is used for all tenant API calls.

Using API Keys

Authentication

All tenant API endpoints require the X-API-Key header:

bash

curl -H "X-API-Key: wp_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://generate.walletpass.ai/v1/pass-styles

Get Tenant Information

bash

curl -H "X-API-Key: wp_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://tenant.walletpass.ai/v1/tenants/info

Response:

json

{
  "status": "success",
  "data": {
    "tenant_id": "tenant-uuid",
    "company_name": "My Company",
    "status": "active",
    "created_at": "2025-01-09T10:30:00Z"
  }
}

Tenant Isolation

Database Schema

Each tenant gets its own PostgreSQL schema:

Schema name: tenant_{tenant_uuid}
Example: tenant_550e8400_e29b_41d4_a716_446655440000

Data Isolation

Members are scoped to tenant
Passes are scoped to tenant
Points transactions are scoped to tenant
Complete data separation

Querying Tenant Data

When using the API, tenant context is automatically resolved from the API key. You don't need to specify tenant ID in requests.