Tenant Management¶

Multi-Tenant Architecture¶

Comprehensive guide to tenant setup, configuration, and management in the Reserva platform.

Overview¶

The Reserva platform implements a two-level multi-tenant architecture designed for businesses managing multiple physical locations (outlets). Each tenant represents a business brand, and outlets represent individual locations under that brand.

Tenant Hierarchy¶

┌─────────────────────────────────────────┐
│         Tenant (Business Brand)         │
│  • Global settings                      │
│  • Subscription plan                    │
│  • Paper.id partner integration         │
│  • Admin users                          │
└────────────┬────────────────────────────┘
             │
    ┌────────┴────────┬──────────────┐
    │                 │              │
┌───▼────┐      ┌────▼───┐     ┌───▼────┐
│Outlet 1│      │Outlet 2│     │Outlet 3│
│Location│      │Location│     │Location│
│   A    │      │   B    │     │   C    │
└────────┘      └────────┘     └────────┘

Key Concepts¶

Tenant Isolation¶

Every database operation is strictly isolated by tenant:

All queries include tenant_id filter
Cross-tenant data access is prevented at the database level
JWT tokens encode tenant context
API endpoints validate tenant ownership

Critical Security Rule

ALWAYS implement tenant isolation in database queries. Failure to do so creates a severe security vulnerability allowing data leakage between tenants.

Outlet Management¶

Outlets are physical locations managed under a tenant:

Each outlet has its own business hours
Staff are assigned to specific outlets
Services can be outlet-specific or tenant-wide
Appointments are booked at outlet level

Tenant Registration¶

Public Self-Service Registration¶

Businesses can register through the public API without authentication. This is the primary onboarding flow for new customers.

Endpoint: POST /api/v1/public/register

Access: Public (no authentication required)

Features:

Instant account activation (no approval required)
Automatic slug generation from business name
Duplicate detection (business name, email, phone)
Strong password validation
FREE subscription plan automatically assigned
Admin user created and ready to login
Paper.id partner account created automatically

Request Example:

{
  "business_name": "Bella Vista Spa",
  "business_email": "contact@bellavista.com",
  "business_phone": "+1-555-987-6543",
  "business_type": "spa",
  "description": "Luxury spa and wellness center",
  "website": "https://bellavista.com",
  "admin_first_name": "Maria",
  "admin_last_name": "Rodriguez",
  "admin_email": "maria@bellavista.com",
  "admin_password": "SecurePass123!",
  "preferred_slug": "bella-vista-spa",
  "terms_accepted": true,
  "privacy_accepted": true
}

Response:

{
  "registration_id": "reg_abc123xyz",
  "tenant_id": "6501234567890abcdef12345",
  "slug": "bella-vista-spa",
  "client_partner_id": "partner_xyz789abc",
  "client_partner_number": "PARTNER-002",
  "status": "active",
  "message": "Registration successful! Your account is now active and ready to use.",
  "next_steps": [
    "1. Log in with your admin credentials",
    "2. Complete your business profile and upload a logo",
    "3. Add your first outlet location with address and business hours",
    "4. Configure your services, pricing, and duration",
    "5. Add staff members and assign them to services",
    "6. Start accepting customer bookings!"
  ]
}

Business Rules:

Password must be at least 8 characters with uppercase, lowercase, and number
Slug auto-generated if not provided
Duplicate slugs auto-incremented (e.g., "salon" → "salon-1")
Website URL auto-prepended with https:// if missing
Terms and privacy policy acceptance required
All new tenants start with FREE subscription plan

Duplicate Detection:

The system prevents duplicates based on:

Business name (case-insensitive)
Business email
Business phone number
Admin email (in users collection)

Next Steps After Registration:

Log in with admin credentials at /api/v1/auth/login
Complete business profile (add logo, update settings)
Create first outlet location
Add services and pricing
Configure staff and working hours
Start accepting bookings!

Admin-Created Tenants¶

System administrators can create tenants directly through the staff portal.

Endpoint: POST /api/v1/tenants

Access: SUPER_ADMIN only

Features:

Atomic operation ensuring both tenant and admin user are created together
Automatic slug generation if not provided
Complete rollback on any failure during creation
Paper.id partner account created automatically
Default subscription settings applied

Request Example:

{
  "name": "Glamour Beauty Spa",
  "slug": "glamour-spa",
  "email": "admin@glamourspa.com",
  "phone": "+639171234567",
  "description": "Premium beauty and wellness services",
  "website": "https://glamourspa.com",
  "admin_email": "owner@glamourspa.com",
  "admin_password": "SecurePass123!",
  "admin_first_name": "Maria",
  "admin_last_name": "Santos",
  "settings": {
    "timezone": "Asia/Manila",
    "currency": "PHP",
    "language": "en",
    "business_type": "spa",
    "staff_position_templates": [
      "Massage Therapist",
      "Senior Therapist",
      "Aesthetician",
      "Spa Manager",
      "Receptionist"
    ],
    "service_category_templates": [
      "massage",
      "body_treatment",
      "facial",
      "spa",
      "therapy",
      "waxing",
      "consultation"
    ]
  }
}

Response:

{
  "id": "6501234567890abcdef12345",
  "name": "Glamour Beauty Spa",
  "slug": "glamour-spa",
  "email": "admin@glamourspa.com",
  "phone": "+639171234567",
  "is_active": true,
  "subscription_id": "507f1f77bcf86cd799439012",
  "client_partner_id": "partner_abc123xyz",
  "client_partner_number": "PARTNER-001",
  "created_at": "2025-10-07T10:30:00Z",
  "updated_at": "2025-10-07T10:30:00Z"
}

Tenant Management Operations¶

List All Tenants¶

Endpoint: GET /api/v1/tenants

Access: SUPER_ADMIN only

Features:

Pagination support with configurable offset and limit
Optional filtering by active/inactive status
Results sorted by creation date (newest first)
Full tenant information including subscription details

Query Parameters:

skip (integer, default: 0): Number of tenants to skip for pagination
limit (integer, default: 100, max: 500): Maximum number of tenants to return
status (string, optional): Filter by 'active' or 'inactive' status

Example Request:

GET /api/v1/tenants?skip=0&limit=20&status=active

Response:

[
  {
    "id": "6501234567890abcdef12345",
    "name": "Glamour Beauty Spa",
    "slug": "glamour-spa",
    "email": "admin@glamourspa.com",
    "is_active": true,
    "subscription": {
      "plan": "pro",
      "status": "active"
    },
    "created_at": "2025-10-07T10:30:00Z"
  }
]

Get Tenant Details¶

Endpoint: GET /api/v1/tenants/{tenant_id}

Access:

SUPER_ADMIN: Can access any tenant
TENANT_ADMIN/OUTLET_MANAGER/STAFF: Can only access their own tenant

Features:

Complete tenant profile including settings and subscription
Automatic tenant access validation based on user role
Full configuration and preference details
Subscription and billing information

Response:

{
  "id": "6501234567890abcdef12345",
  "name": "Glamour Beauty Spa",
  "slug": "glamour-spa",
  "email": "admin@glamourspa.com",
  "phone": "+639171234567",
  "description": "Premium beauty and wellness services",
  "website": "https://glamourspa.com",
  "is_active": true,
  "subscription": {
    "plan": "pro",
    "status": "active",
    "trial_ends_at": null,
    "current_period_start": "2025-10-01T00:00:00Z",
    "current_period_end": "2025-11-01T00:00:00Z"
  },
  "settings": {
    "timezone": "Asia/Manila",
    "currency": "PHP",
    "language": "en",
    "business_type": "spa",
    "staff_position_templates": [
      "Massage Therapist",
      "Senior Therapist",
      "Aesthetician",
      "Spa Manager",
      "Receptionist"
    ],
    "service_category_templates": [
      "massage",
      "body_treatment",
      "facial",
      "spa",
      "therapy",
      "waxing",
      "consultation"
    ],
    "booking_advance_days": 30,
    "cancellation_hours": 24,
    "wallet_enabled": true,
    "loyalty_points_enabled": false
  },
  "client_partner_id": "partner_abc123xyz",
  "subscription_id": "507f1f77bcf86cd799439012",
  "created_at": "2025-10-07T10:30:00Z",
  "updated_at": "2025-10-07T10:30:00Z"
}

Update Tenant¶

Endpoint: PUT /api/v1/tenants/{tenant_id}

Access:

SUPER_ADMIN: Can update any tenant
TENANT_ADMIN: Can only update their own tenant

Features:

Partial updates supported for all tenant fields
Settings updates including wallet, loyalty, and payment configurations
Staff position templates customization for business-specific roles
Subscription and billing settings modification (except plan - use subscription endpoints)
Historical data preserved during updates

Business Rules:

Slug cannot be updated (intentionally excluded to prevent breaking integrations)
Cannot update subscription status directly (use /api/v1/subscriptions/* endpoints)
Settings changes apply immediately to all outlets
Position template updates affect staff creation forms but don't change existing staff positions

Request Example:

{
  "name": "Glamour Beauty & Wellness Spa",
  "description": "Premium beauty, wellness and massage services",
  "phone": "+639171234568",
  "settings": {
    "timezone": "Asia/Manila",
    "currency": "PHP",
    "language": "en"
  }
}

Response: Returns updated tenant object with all changes applied.

Staff Position Templates¶

Staff position templates provide flexible, business-specific role definitions for staff members. Instead of using a fixed list of positions, each tenant can customize positions to match their business terminology.

Configuration Location: settings.staff_position_templates in tenant settings

Default Templates:

[
  "Service Provider",
  "Senior Provider",
  "Specialist",
  "Manager",
  "Receptionist",
  "Assistant",
  "Trainee"
]

Business-Specific Examples:

Business Type	Position Templates
Salon	Junior Stylist, Senior Stylist, Colorist, Barber, Manager, Receptionist
Spa	Massage Therapist, Senior Therapist, Aesthetician, Holistic Practitioner, Spa Manager, Receptionist
Fitness Center	Personal Trainer, Yoga Instructor, Pilates Instructor, Nutritionist, Gym Manager, Front Desk
Medical Clinic	Nurse, Physiotherapist, Medical Assistant, Clinic Manager, Receptionist
Beauty Salon	Nail Technician, Lash Artist, Makeup Artist, Brow Specialist, Salon Manager, Receptionist

How to Configure:

During Tenant Creation - Include in settings:

{
  "settings": {
    "staff_position_templates": [
      "Junior Stylist",
      "Senior Stylist",
      "Colorist",
      "Manager",
      "Receptionist"
    ]
  }
}

Update Existing Tenant - Modify via PUT endpoint:

{
  "settings": {
    "staff_position_templates": [
      "Massage Therapist",
      "Senior Therapist",
      "Aesthetician",
      "Spa Manager",
      "Receptionist"
    ]
  }
}

Retrieve Templates API:

GET /api/v1/staff/positions/templates

Returns the current tenant's position templates for use in staff creation forms and dropdowns.

Key Features:

✅ Fully customizable per tenant
✅ No code changes needed for new business types
✅ Used for autocomplete/suggestions in UI
✅ Staff can still enter custom positions not in templates
✅ Updating templates doesn't affect existing staff positions
✅ Helps maintain consistency in position naming

Best Practice

Configure position templates during tenant setup to match your business terminology. This ensures consistency when creating staff members and makes filtering/reporting by position more meaningful.

Service Category Templates¶

Service category templates provide flexible, business-specific service categorization for the service catalog. Instead of using a fixed list of categories, each tenant can customize categories to match their service offerings and business type.

Configuration Location: settings.service_category_templates in tenant settings

Default Templates:

[
  "hair_cut",
  "hair_color",
  "hair_treatment",
  "hair_styling",
  "facial",
  "makeup",
  "eyebrows",
  "eyelashes",
  "manicure",
  "pedicure",
  "nail_art",
  "massage",
  "body_treatment",
  "waxing",
  "spa",
  "therapy",
  "consultation",
  "other"
]

Business-Specific Examples:

Business Type	Service Category Templates
Salon	hair_cut, hair_color, hair_treatment, hair_styling, makeup, manicure, pedicure, nail_art, waxing
Spa	massage, body_treatment, facial, spa, therapy, waxing, consultation
Fitness Center	personal_training, yoga, pilates, cardio, strength_training, nutrition, consultation
Medical Clinic	consultation, therapy, physiotherapy, assessment, treatment, follow_up
Beauty Salon	facial, makeup, eyebrows, eyelashes, manicure, pedicure, nail_art, waxing

How to Configure:

During Tenant Creation - Include in settings:

{
  "settings": {
    "service_category_templates": [
      "hair_cut",
      "hair_color",
      "hair_treatment",
      "hair_styling",
      "makeup",
      "manicure",
      "pedicure"
    ]
  }
}

Update Existing Tenant - Modify via PUT endpoint:

{
  "settings": {
    "service_category_templates": [
      "massage",
      "body_treatment",
      "facial",
      "spa",
      "therapy",
      "waxing",
      "consultation"
    ]
  }
}

Retrieve Templates API:

GET /api/v1/services/categories/templates

Returns the current tenant's service category templates for use in service creation forms and dropdowns.

Key Features:

✅ Fully customizable per tenant
✅ No code changes needed for new business types
✅ Used for autocomplete/suggestions in UI
✅ Services can use categories from templates or custom values
✅ Updating templates doesn't affect existing service categories
✅ Helps maintain consistency in service organization
✅ Improves customer browsing experience with relevant categories

Best Practice

Configure service category templates during tenant setup to match your service offerings. This ensures consistent categorization across your service catalog and makes filtering/browsing services more intuitive for customers.

Deactivate Tenant¶

Endpoint: DELETE /api/v1/tenants/{tenant_id}

Access: SUPER_ADMIN only

Status Code: 204 No Content

Features:

Soft delete operation (sets is_active = False)
Preserves all historical data and relationships
Prevents new operations while maintaining audit trail
Cascades deactivation to related outlets and users

Business Rules:

No data is permanently deleted from the system
All appointments and customer data remain accessible
Billing and subscription history preserved
Users associated with tenant are also deactivated
Operation can be reversed by SUPER_ADMIN if needed

Process:

Validate tenant exists and user permissions
Set tenant status to inactive
Deactivate all associated outlets
Deactivate all tenant users except SUPER_ADMIN
Update subscription status to suspended

Get Tenant Statistics¶

Endpoint: GET /api/v1/tenants/{tenant_id}/stats

Access:

SUPER_ADMIN: Can access any tenant statistics
TENANT_ADMIN: Can only access their own tenant statistics

Features:

Complete outlet and user analytics
Customer acquisition and retention metrics
Appointment volume and status distribution
Revenue and subscription insights
Real-time data with historical trends

Statistics Include:

Outlet count with active/inactive breakdown
User distribution by role and status
Customer metrics including recent signups (last 30 days)
Appointment volume for current month with status breakdown
Subscription plan and billing status

Response Example:

{
  "outlets": {
    "total": 3,
    "active": 3,
    "inactive": 0
  },
  "users": {
    "total": 15,
    "active": 15,
    "by_role": {
      "tenant_admin": 2,
      "outlet_manager": 3,
      "staff": 8,
      "receptionist": 2
    }
  },
  "customers": {
    "total": 1250,
    "active": 1180,
    "recent_signups": 45
  },
  "appointments": {
    "this_month": 380,
    "this_month_by_status": {
      "confirmed": 120,
      "pending": 45,
      "completed": 180,
      "cancelled": 25,
      "no_show": 10
    }
  },
  "subscription": {
    "plan": "pro",
    "status": "active",
    "trial_ends_at": null
  },
  "generated_at": "2025-10-07T15:30:00Z",
  "tenant_info": {
    "id": "6501234567890abcdef12345",
    "name": "Glamour Beauty Spa",
    "slug": "glamour-spa",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Paper.id Integration¶

The platform integrates with Paper.id payment gateway to enable appointment payments and financial transactions. Each tenant has two levels of Paper.id integration:

1. Platform-Level Partner Account (Automatic)¶

Upon tenant creation (both public registration and admin-created), the system automatically creates a Paper.id partner account:

Partner Account Creation:

Registers business with Paper.id payment gateway
Receives unique client_partner_id (UUID for partner operations)
Receives unique client_partner_number (custom identifier for invoice operations)
Stores partner identifiers in tenant record

Financial Features Enabled:

Invoice generation and management
Payment collection and processing
Merchant withdrawals and payouts
Platform fee calculation and tracking

Partner Account Details

The system tracks TWO Paper.id partner identifiers: - client_partner_id: UUID used for partner operations (GET /partners/{id}) - client_partner_number: Custom identifier used for invoice customer.id field (POST /store-invoice)

If Paper.id integration fails during registration, the tenant is still created successfully, but payment features will be limited until manual partner setup.

2. Tenant-Specific Payment Configuration (Manual)¶

Tenants can configure their own Paper.id credentials to receive appointment payments directly to their own Paper.id merchant account. This is optional and configured via dedicated endpoints.

Configuration Features:

Tenant-specific client_id and client_secret (encrypted AES-256)
Production vs sandbox mode selection
Enable/disable toggle for payment processing
Automatic encryption of sensitive credentials
Secure storage with no secret exposure in API responses

Configuration Endpoints:

Endpoint	Method	Access	Description
`/api/v1/tenants/{tenant_id}/paper-id-config`	PUT	TENANT_ADMIN+	Update Paper ID configuration
`/api/v1/tenants/{tenant_id}/paper-id-config`	GET	TENANT_ADMIN+	Get configuration status
`/api/v1/tenants/{tenant_id}/paper-id-config`	DELETE	TENANT_ADMIN+	Disable configuration

See Tenant Paper.id Configuration section below for detailed endpoint documentation.

Subscription Management¶

Available Plans¶

All new tenants start with the FREE plan. They can upgrade anytime through subscription management endpoints.

Plan	Features
FREE	1 outlet, 5 staff, 100 appointments/month, 1GB storage
BASIC	3 outlets, 15 staff, 500 appointments/month, 10GB storage
PRO	10 outlets, 50 staff, 2000 appointments/month, 50GB storage
ENTERPRISE	Unlimited outlets, staff, appointments, storage + white label

Subscription Endpoints¶

Subscription management is handled through dedicated endpoints:

GET /api/v1/subscriptions/current - Get current subscription details
POST /api/v1/subscriptions/upgrade - Upgrade subscription plan
POST /api/v1/subscriptions/downgrade - Downgrade subscription plan
GET /api/v1/subscriptions/usage - Check current usage against limits
GET /api/v1/subscriptions/payments - Get payment history

See the Subscriptions documentation for full details.

Outlet Management¶

Outlets represent physical business locations under a tenant. Each tenant can have multiple outlets based on their subscription plan.

Key Outlet Operations¶

Endpoint	Method	Access	Description
`/api/v1/outlets`	GET	Staff Portal	List all outlets for tenant
`/api/v1/outlets`	POST	TENANT_ADMIN+	Create new outlet
`/api/v1/outlets/{outlet_id}`	GET	Staff Portal	Get outlet details
`/api/v1/outlets/{outlet_id}`	PUT	TENANT_ADMIN+	Update outlet
`/api/v1/outlets/{outlet_id}`	DELETE	TENANT_ADMIN+	Delete outlet
`/api/v1/outlets/stats`	GET	TENANT_ADMIN+	Outlet statistics

See the Outlets documentation for full API reference.

User & Staff Management¶

User Roles (RBAC)¶

The platform implements role-based access control:

Role	Description	Tenant Access
SUPER_ADMIN	Platform administrator	All tenants
TENANT_ADMIN	Tenant owner/administrator	Own tenant only
OUTLET_MANAGER	Outlet manager	Own tenant only
STAFF	Service provider	Own tenant only
RECEPTIONIST	Front desk	Own tenant only

User Endpoints¶

Endpoint	Method	Access	Description
`/api/v1/users`	GET	TENANT_ADMIN+	List users in tenant
`/api/v1/users`	POST	TENANT_ADMIN+	Create new user
`/api/v1/users/{user_id}`	GET	TENANT_ADMIN+	Get user details
`/api/v1/users/{user_id}`	PUT	TENANT_ADMIN+	Update user
`/api/v1/users/{user_id}`	DELETE	TENANT_ADMIN+	Deactivate user
`/api/v1/users/{user_id}/reset-password`	POST	TENANT_ADMIN+	Reset user password

Staff vs Users¶

User vs Staff Distinction

Users: System access accounts (login credentials, roles, permissions)
Staff: Service providers with skills, availability, and commission settings

A staff member providing services will have both:

User account (for system login) - created via /api/v1/users
Staff profile (for service delivery, scheduling) - created via /api/v1/staff

Authentication & Security¶

Staff Portal Authentication¶

Endpoint: POST /api/v1/auth/login

Login Flow:

Initial Login - Email/password authentication
Organization Selection - Choose tenant if user belongs to multiple
Complete Login - Receive JWT token with tenant context

Token Structure:

{
  "sub": "user_id",
  "tenant_id": "6501234567890abcdef12345",
  "role": "tenant_admin",
  "outlet_ids": ["outlet1", "outlet2"],
  "exp": 1735737000
}

Security Features¶

JWT Tokens - Secure, stateless authentication with 30-minute expiration
Role-Based Access Control - Granular permissions per endpoint
Password Policies - Strong password requirements enforced
Audit Logging - Comprehensive activity tracking for compliance
OWASP Headers - Security best practices implemented
Rate Limiting - API abuse prevention (public endpoints have 30% of authenticated limits)

Data Export & Compliance¶

Export Tenant Data¶

Endpoint: GET /api/v1/tenants/{tenant_id}/export

Access: TENANT_ADMIN+

Description: Export all tenant data for GDPR compliance and data portability.

Features:

Complete data export in JSON format
Includes all appointments, customers, invoices, payments
Historical records included
Suitable for backup and migration purposes

Tenant Paper.id Configuration¶

Tenants can configure their own Paper.id credentials to enable appointment payment processing directly to their merchant account. This is separate from the platform-level partner account and provides tenant-specific payment control.

Update Paper.id Configuration¶

Endpoint: PUT /api/v1/tenants/{tenant_id}/paper-id-config

Access:

SUPER_ADMIN: Can update any tenant's configuration
TENANT_ADMIN: Can only update their own tenant's configuration

Features:

Automatic encryption of client_secret using AES-256 (Fernet) before storage
Creates or updates Paper.id configuration for tenant
Validates client credentials format
Supports both production and sandbox modes

Security:

client_secret is encrypted before database storage
Encrypted secret is never exposed in API responses
Only client_id and configuration metadata are returned

Request Example:

{
  "client_id": "tenant_client_id_12345",
  "client_secret": "your_secret_key_here",
  "is_production": true,
  "enabled": true
}

Response:

{
  "client_id": "tenant_client_id_12345",
  "is_production": true,
  "enabled": true,
  "created_at": "2025-10-13T10:00:00Z",
  "updated_at": "2025-10-13T10:00:00Z"
}

Business Rules:

Tenant must exist and be active
Configuration is stored in paper_id_config field
Setting enabled=false disables Paper.id payments for tenant
Changes take effect immediately for new appointments
The client_secret is never returned in responses for security

Get Paper.id Configuration¶

Endpoint: GET /api/v1/tenants/{tenant_id}/paper-id-config

Access:

SUPER_ADMIN: Can access any tenant's configuration
TENANT_ADMIN: Can only access their own tenant's configuration

Features:

Returns Paper.id configuration metadata
Shows enabled/disabled status
Displays production/sandbox mode
Never exposes encrypted client_secret

Response:

{
  "client_id": "tenant_client_id_12345",
  "is_production": true,
  "enabled": true,
  "created_at": "2025-10-13T10:00:00Z",
  "updated_at": "2025-10-13T10:00:00Z"
}

Returns:

client_id: Tenant's Paper.id client ID
is_production: Production vs sandbox mode (true = production)
enabled: Whether Paper.id is enabled for this tenant
created_at: When configuration was created
updated_at: When configuration was last updated

Note: Returns 404 if tenant has not configured Paper.id yet.

Disable Paper.id Configuration¶

Endpoint: DELETE /api/v1/tenants/{tenant_id}/paper-id-config

Access:

SUPER_ADMIN: Can disable any tenant's configuration
TENANT_ADMIN: Can only disable their own tenant's configuration

Status Code: 204 No Content

Features:

Sets enabled=false in configuration
Preserves all configuration data and encrypted secret
Can be re-enabled later without re-entering credentials
Takes effect immediately for new appointments

Business Rules:

Configuration data is not deleted, only disabled
Existing appointments are not affected
New appointments cannot use Paper.id until re-enabled
Can be re-enabled via PUT endpoint with enabled=true

Note: This is a soft disable. Use PUT endpoint with enabled=true to re-enable without re-entering credentials.

Best Practices¶

Tenant Setup Checklist¶

After registering a new tenant, follow these steps:

[ ] Register tenant via public API (/api/v1/public/register)
[ ] Log in with admin credentials (/api/v1/auth/login)
[ ] Verify Paper.id integration succeeded (check client_partner_id in tenant details)
[ ] Update tenant settings: timezone, currency, language
[ ] Configure staff position templates to match your business terminology
[ ] Configure service category templates to match your service offerings
[ ] Create first outlet with accurate address and business hours
[ ] Add services to catalog with pricing and duration
[ ] Create staff profiles with skills and availability
[ ] Assign staff to outlets and services
[ ] Test appointment booking workflow
[ ] Configure payment methods and verify test transaction

Security Recommendations¶

Security Best Practices

Use strong passwords - Enforce 8+ characters with uppercase, lowercase, and number
Limit TENANT_ADMIN access - Grant admin roles only to trusted users
Regular audits - Review audit logs for suspicious activity
Monitor usage - Track subscription limits to prevent service disruption
Rotate API keys - Rotate Paper.id API keys periodically
Enable 2FA - Two-factor authentication (coming soon)

API Reference¶

Complete Tenant Endpoints Summary¶

Endpoint	Method	Access	Description
`/api/v1/public/register`	POST	Public	Self-service tenant registration
`/api/v1/tenants`	GET	SUPER_ADMIN	List all tenants
`/api/v1/tenants`	POST	SUPER_ADMIN	Create tenant (admin)
`/api/v1/tenants/{tenant_id}`	GET	Staff Portal	Get tenant details
`/api/v1/tenants/{tenant_id}`	PUT	TENANT_ADMIN+	Update tenant
`/api/v1/tenants/{tenant_id}`	DELETE	SUPER_ADMIN	Deactivate tenant
`/api/v1/tenants/{tenant_id}/stats`	GET	TENANT_ADMIN+	Get statistics
`/api/v1/tenants/{tenant_id}/paper-id-config`	PUT	TENANT_ADMIN+	Update Paper ID config
`/api/v1/tenants/{tenant_id}/paper-id-config`	GET	TENANT_ADMIN+	Get Paper ID config
`/api/v1/tenants/{tenant_id}/paper-id-config`	DELETE	TENANT_ADMIN+	Disable Paper ID config

Overview - Platform overview and features
Swagger UI - Interactive API documentation
ReDoc - API reference documentation

For detailed endpoint specifications, request/response schemas, and interactive testing, visit the Swagger UI.

Tenant Management¶

Multi-Tenant Architecture¶

Overview¶

Tenant Hierarchy¶

Key Concepts¶

Tenant Isolation¶

Outlet Management¶

Tenant Registration¶

Public Self-Service Registration¶

Admin-Created Tenants¶

Tenant Management Operations¶

List All Tenants¶

Get Tenant Details¶

Update Tenant¶

Staff Position Templates¶

Service Category Templates¶

Deactivate Tenant¶

Get Tenant Statistics¶

Paper.id Integration¶

1. Platform-Level Partner Account (Automatic)¶

2. Tenant-Specific Payment Configuration (Manual)¶

Subscription Management¶

Available Plans¶

Subscription Endpoints¶

Outlet Management¶

Key Outlet Operations¶

User & Staff Management¶

User Roles (RBAC)¶

User Endpoints¶

Staff vs Users¶

Authentication & Security¶

Staff Portal Authentication¶

Security Features¶

Data Export & Compliance¶

Export Tenant Data¶

Tenant Paper.id Configuration¶

Update Paper.id Configuration¶

Get Paper.id Configuration¶

Disable Paper.id Configuration¶

Best Practices¶

Tenant Setup Checklist¶

Security Recommendations¶

API Reference¶

Complete Tenant Endpoints Summary¶

Related Resources¶