Skip to main content

Organizations

Understanding the organization structure and how it works in DPaaS.

Overview​

An Organization is the top-level container in DPaaS that represents a tenant, customer, or company. Organizations provide complete isolation between different tenants.

What is an Organization?​

Think of an organization as your company's entire workspace in PDaaS:

  • Complete Isolation: Each organization is completely separated from others
  • Single Billing Entity: One organization = one subscription/billing entity
  • Unique Identifier: Each org has a unique 6-character slug (e.g., abc123)
  • Resource Container: Contains all accounts, users, service accounts, policies, and groups

Organization Structure​

Organization (Acme Corp - slug: abc123)
├── Accounts
│   ├── Production
│   ├── Staging
│   └── Development
├── Users
│   ├── [email protected]
│   ├── [email protected]
│   └── [email protected]
├── Service Accounts
│   ├── CI/CD Bot
│   └── Monitoring Bot
├── Groups
│   ├── Administrators
│   └── Developers
└── Policies
    ├── AdminAccess
    └── ReadOnlyAccess

Organization Slug​

The slug is a unique 6-character identifier:

  • Format: [0-9a-z]{6} (lowercase letters and numbers only)
  • Example: abc123, xyz789
  • Used in: API key prefixes, subdomains, routing
  • Cannot be changed after creation

Slug Usage Examples​

API Keys:

sa_abc123_acc456_xyz789
   ^^^^^^
   org slug

Subdomains (optional):

abc123.console.solucao42.com.br

Multi-Organization vs Single-Organization​

When to Use Multiple Organizations​

✅ Separate Customers (B2B SaaS)

  • Each customer gets their own organization
  • Complete data isolation
  • Independent billing

✅ Different Legal Entities

  • Your US company = org A
  • Your EU company = org B
  • Separate compliance requirements

✅ Staging vs Production Environments (at org level)

  • Production org for live customers
  • Staging org for testing

When to Use Single Organization​

✅ Internal Company Use

  • One company using PDaaS internally
  • Use accounts to separate departments/projects

✅ Small Teams

  • Single customer/project
  • Use accounts for environment separation

Organization Metadata​

Organizations can store custom metadata:

{
  "id": "org-abc123xyz",
  "name": "Acme Corporation",
  "slug": "abc123",
  "metadata": {
    "industry": "Technology",
    "size": "Enterprise",
    "region": "North America",
    "customer_tier": "Premium",
    "onboarding_date": "2025-01-15"
  }
}

Use cases for metadata:

  • Customer segmentation
  • Feature flags
  • Billing tier information
  • Compliance tracking
  • Custom attributes

Common Patterns​

Pattern 1: B2B SaaS Platform​

Each customer is an organization:

Customer A (org: cust01) → Their own isolated workspace
Customer B (org: cust02) → Their own isolated workspace
Customer C (org: cust03) → Their own isolated workspace

Pattern 2: Internal Company​

Single organization with accounts:

Acme Corp (org: acme01)
├── Engineering Account
├── Sales Account
└── Marketing Account

Pattern 3: Multi-Region​

Separate organizations by region:

Acme US (org: acmeus)   → US data center
Acme EU (org: acmeeu)   → EU data center
Acme APAC (org: acmeap) → APAC data center

Organization Isolation​

Organizations are completely isolated:

Data Isolation​

  • Users cannot see data from other organizations
  • Service accounts are scoped to their organization
  • API keys only work within their organization

Authentication Isolation​

  • Users authenticate with organization_slug
  • JWT tokens include organization ID
  • Cross-org authentication is not possible

Resource Isolation​

  • Policies only apply within the organization
  • Groups cannot span organizations
  • Accounts belong to exactly one organization

Provisioning a New Organization​

When creating a new organization, PDaaS automatically:

  1. Creates Default Account - Every org needs at least one account
  2. Generates Unique Slug - If not provided
  3. Sets Up Default Policies - Basic permission templates (optional)
  4. Creates Admin User - First user with full access (optional)

Organization Limits​

Organizations may have limits based on your plan:

ResourceTypical Limits
Accounts100-1000
Users1000-10000
Service Accounts100-500
Groups50-200
Policies100-500

Note: Limits are configurable per deployment.

Organization Management​

Get Organization Info​

curl https://api.console.solucao42.com.br/organizations/info \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  ...

Update Organization​

curl -X PATCH https://api.console.solucao42.com.br/organizations/info \
  -H "Authorization: HMAC sa_abc123_acc456_xyz:signature" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation Inc.",
    "metadata": {
      "industry": "Technology"
    }
  }'

Best Practices​

✅ DO​

  • Use meaningful names - "Acme Corporation" not "Org 1"
  • Add metadata early - Easier to query/segment later
  • Plan account structure - Before adding many users
  • Use slugs consistently - Don't rely on IDs in code

❌ DON'T​

  • Share organizations - Each customer should have their own
  • Store sensitive data in metadata - Use proper secret management
  • Hardcode slugs - Use environment variables or configuration
  • Try to change slugs - They're immutable after creation

Security Considerations​

Subdomain Routing​

If using subdomain-based routing:

https://abc123.console.solucao42.com.br
  • Prevents org slug leakage in URLs
  • Cleaner URLs for end users
  • Better for white-labeling

API Key Prefixes​

API keys include the org slug:

sa_abc123_acc456_xyz789
  • Prevents accidental cross-org usage
  • Easy to identify which org a key belongs to
  • Helps with key rotation auditing

API Reference​

For API details, see:

Next Steps​