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 '{
    "company_name": "My Company",
    "contact_email": "contact@mycompany.com",
    "contact_name": "John Doe"
  }'

Response:

json

{
  "status": "success",
  "message": "Tenant onboarded successfully",
  "data": {
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "api_key": "wp_864e820cbbabce90ead1bc429eec64ed",
    "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_864e820cbbabce90ead1bc429eec64ed" \
  https://generate.walletpass.ai/v1/pass-styles

Get Tenant Information

bash

curl -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  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"
  }
}

Admin System

Roles

Super Admin - Can create admins and manage all tenants
Admin - Can create and manage own tenants
Tenant - Uses API keys for normal operations

Create Admin (Super Admin Only)

bash

curl -X POST https://tenant.walletpass.ai/v1/admins \
  -H "Authorization: Bearer admin@walletpass.ai" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "partner@example.com",
    "password": "SecurePassword123!",
    "name": "Partner Admin",
    "role": "admin"
  }'

Admin Creates Own Bearer Token

bash

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

Admin Creates Own Tenant

bash

curl -X POST https://tenant.walletpass.ai/v1/onboard \
  -H "Authorization: Bearer bt_partner_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Partner Company",
    "contact_email": "contact@partner.com",
    "contact_name": "Partner Contact"
  }'

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.