Multi-Tenancy

Understand how StackForDevs organizes your account with tenants and projects for secure data isolation.

💡 What is Multi-Tenancy in StackForDevs? Your StackForDevs tenant is your organization's account. Within your tenant, you create projects for each distinct SaaS product you're building. Each project is used across all environments (dev, staging, production) and all platforms (web, mobile). StackForDevs ensures data isolation between your projects.

Key Concepts

StackForDevs implements a two-tier multi-tenancy model:

🏢 Tenant

A tenant represents you - a customer of StackForDevs itself. This is your organization's account. Each tenant has:

One StackForDevs account with billing and subscription
Independent usage quotas
One or more projects (your SaaS apps/environments)
Complete data isolation from other StackForDevs customers

📁 Project

A project represents one distinct SaaS product or application that you're building. Each project has:

Independent API keys per project
Project-level usage tracking
Users live within the context of a Project
Shared across all environments (dev, staging, production)
Shared across all platforms (web, mobile, admin portal)

Example: If you're building two SaaS products - a task management app and a CRM - each would be a separate project.

Architecture Hierarchy

Your StackForDevs Account (Tenant = You)
  ├── Project 1 (Task Management SaaS)
  │   ├── API Keys (Public & Secret)
  │   ├── Users (across web, mobile, all environments)
  │   └── Data (tasks, projects, teams)
  ├── Project 2 (CRM SaaS)
  │   ├── API Keys (Public & Secret)
  │   ├── Users (across web, mobile, all environments)
  │   └── Data (contacts, deals, pipelines)
  └── Project 3 (Analytics Dashboard)
      ├── API Keys (Public & Secret)
      ├── Users (across all platforms/environments)
      └── Data (metrics, reports, insights)

Working with Tenants

Every API request must include a tenant ID to ensure proper data isolation:

Tenant ID in Headers

POST https://auth.stackfordevs.com/v1/register
Headers:
  x-api-key: YOUR_PUBLIC_KEY
  x-secret-key: YOUR_SECRET_KEY
  x-tenant-id: YOUR_TENANT_ID          ← Required for isolation
  x-project-id: YOUR_PROJECT_ID
  Content-Type: application/json

Getting Your Tenant ID

Find your tenant ID in the admin dashboard:

Log in to your StackForDevs account
Look for the tenant selector in the header
Your tenant ID is displayed next to the tenant name

Understanding Your Tenant ID

Most StackForDevs customers will have one tenant - your organization's account. You use the same tenant ID across all your projects.

💡 Important: If you're building a multi-tenant SaaS application with multiple customer organizations, those are not separate StackForDevs tenants. You handle customer data isolation by using separate projects. All your projects use your single StackForDevs tenant ID.

// Load from environment variables
const yourTenantId = process.env.STACKFORDEVS_TENANT_ID;

// Different projects for different SaaS products
// Task Manager
const taskManagerProjectId = process.env.TASK_MANAGER_PROJECT_ID;
const taskManagerApiKey = process.env.TASK_MANAGER_API_KEY;
const taskManagerSecretKey = process.env.TASK_MANAGER_SECRET_KEY;

// CRM
const crmProjectId = process.env.CRM_PROJECT_ID;
const crmApiKey = process.env.CRM_API_KEY;
const crmSecretKey = process.env.CRM_SECRET_KEY;

// Task Manager app requests (same project for dev, staging, prod, web, mobile)
fetch('https://auth.stackfordevs.com/v1/register', {
  headers: {
    'x-tenant-id': yourTenantId,        // Your StackForDevs account
    'x-project-id': taskManagerProjectId, // Task Manager product
    'x-api-key': taskManagerApiKey,
    'x-secret-key': taskManagerSecretKey
  }
});

// CRM app requests (different product = different project)
fetch('https://auth.stackfordevs.com/v1/register', {
  headers: {
    'x-tenant-id': yourTenantId,       // Same tenant ID
    'x-project-id': crmProjectId,      // CRM product
    'x-api-key': crmApiKey,
    'x-secret-key': crmSecretKey
  }
});

Working with Projects

Each project represents one distinct SaaS product or application. Use the same project across all environments (dev, staging, production) and all platforms (web, mobile, admin).

When to Create a New Project

✓ Multiple Distinct Products

Create separate projects when building completely different SaaS products:

Project 1: Task Management SaaS (web + mobile + API)
Project 2: CRM Platform (web + mobile + API)
Project 3: Analytics Dashboard (web only)

✓ Each product has independent users, data, and billing tracking

✗ NOT for Environments or Platforms

Do NOT create separate projects for:

❌ Environments: Dev, staging, production should share the same project
❌ Platforms: Web, mobile, admin should share the same project
❌ Regions: US, EU, APAC deployments should share the same project

⚠ Using different projects for these creates configuration drift and complexity

⚠️ Best Practice: Use environment variables to handle dev/staging/production differences within your code. Keep the same StackForDevs project ID across all environments for a given product.

Creating Projects

Create and manage projects through the dashboard:

Navigate to Projects Page
Enter a name for your product (e.g., "Task Manager", "CRM", "Analytics Dashboard")
Click "Create Project"
API keys are automatically generated for your new project
Use the same project ID and keys across all environments and platforms

Project-Level Usage Tracking

Monitor usage breakdown by project (product) on the Usage page in the Admin Dashboard. You can view detailed metrics, costs, and trends for each of your projects.