Documentation/Account & Billing/Workspace, Domains & Tenants

Workspace, Domains & Tenants

What your Supero workspace actually is, how the Domain -> Project -> Tenant hierarchy fits together, and how to register a domain, scope API keys, add team members, and turn on sub-tenant multi-tenancy or SSO as you grow.

Overview

A Supero "workspace" is your account on the platform. In Supero's own hierarchy that top level is called a Domain, and everything else you manage day to day -- projects, tenants, team members, API keys, and billing -- hangs underneath it. This page is the map: how the account hierarchy fits together, how to register a domain and scope credentials correctly, how to add team members, and how to turn on plan-gated account features like sub-tenant multi-tenancy and SSO as your app grows.

ℹ️ A note on "tenant"

Some people casually call their whole Supero account a "tenant" -- that usage really means the Domain. In Supero's own hierarchy, Tenant is a narrower, specific level below Project: the data-isolation boundary for one of your app's own customers. This page always uses "tenant" in that narrower, hierarchy sense unless stated otherwise.

The Account Hierarchy

Every object in Supero -- schemas, records, users, API keys -- lives under a fixed ownership hierarchy rooted at your Domain:

text

Domain                    (your account -- what most other platforms call a "workspace" or "organization")
  └─ Project              (one application; every domain gets a default-project automatically)
       └─ Tenant          (one of your app's own customers; every project gets a default-tenant automatically)
            ├─ UserAccount
            └─ ApiKey

Level	What it is	Example
Domain	Your top-level Supero account. Domain names are globally unique and every project, schema, and record you create lives under one.	"acme-corp"
Project	An isolated backend environment inside your domain -- its own schemas, data, and generated CRUD API surface.	"storefront", "mobile-api"
Tenant	The data-isolation boundary inside a project -- one of your app's own customers or workspaces. Every project gets a default-tenant automatically.	"acme-industries" (a customer), "default-tenant"
UserAccount / ApiKey	The credentials that authenticate as a specific tenant -- a person (UserAccount) or a machine credential (ApiKey).	"[email protected]", "ak_..."

Namespace is a separate, orthogonal concept -- a label used to group and qualify schemas, not another level of this hierarchy. See Core Concepts for the full schema model.

Registering a Domain

Registering a domain creates your account and its first admin user in a single call. That admin is created with the domain_admin role, inside the new domain's default-tenant.

bash

curl -X POST https://api.supero.dev/api/v1/domains/register \
  -H "Content-Type: application/json" \
  -d '{
    "domain_name": "acme-corp",
    "admin_email": "[email protected]",
    "admin_password": "SecurePass123!",
    "domain_display_name": "Acme Corp"
  }'

domain_name must be unique across the platform and use only lowercase letters, numbers, and hyphens; domain_display_name is optional. Once the domain is registered, log in with the admin credentials (POST /api/v1/auth/login) to get an access token for everything else on this page. The full domain, project, and tenant endpoints are in the Domains, Projects & Tenants API.

API Keys and Credential Scope

Alongside a logged-in user's JWT, you can authenticate server-to-server calls with an API key sent in the X-API-Key header. A key is minted for a specific point in the hierarchy -- a domain, a project, or (most commonly) a single tenant -- and inherits that scope on every request; you never pass a separate domain, project, or tenant identifier alongside it. Create one from the dashboard or via POST /api/v1/domains/{domain}/api-key.

text

ak_{domain}_{project}_{tenant}_{env}_{uuid}_{secret}

That shape is illustrative only -- treat the whole key value as one opaque secret. Your code should never parse or derive scope from it; read the resolved scope back from GET /api/v1/auth/session or /api/v1/auth/me instead.

🚨 Bearer vs X-API-Key

Never send an API key as a Bearer token. Authorization: Bearer <token> is reserved for JWT access tokens issued by login; API keys always go in X-API-Key.

Team Members and Roles

There's no separate "workspace member" object. Adding a person to your workspace means creating a UserAccount scoped to a tenant, a project, or the whole domain, with one role from Supero's fixed role catalog -- the same mechanism you'd use to create a user for your own app's customers.

Role scope	Sees
domain_admin / domain_user	Every project and tenant in the domain.
project_admin / project_user / developer	Every tenant inside their own project (not other projects).
tenant_admin / tenant_user / viewer	Only their own tenant.

platform_admin and platform_user sit above domain_admin but are reserved for Supero staff running the platform itself -- do not present them as an option in your own team's user management.

Users & Roles covers the full role catalog, custom roles, and account lifecycle (create, disable, move between tenants) in depth; this page only covers the account-level shape.

Sub-Tenant Multi-Tenancy

If your own app is itself multi-tenant SaaS, each of your customers is a Tenant under your project, and Supero enforces that isolation for you on every request (see Building Multi-Tenant Apps for the mechanics). Every plan includes a baseline amount of tenant capacity, and sub-tenant multi-tenancy becomes a headline, fully-provisioned capability from the Pro plan up.

💡 Need more tenant slots?

Extend your tenant capacity with the Multi-tenancy add-on -- it's sold in stackable blocks on top of your plan's baseline and is available on any plan, not just Pro and above. Current allowances and add-on pricing are on the Billing screen in your dashboard at app.supero.dev/billing and are subject to change.

Single Sign-On (SSO)

Team members can sign in to the Supero dashboard through your company's identity provider over SAML 2.0 or OIDC instead of a password.

ℹ️ Plan availability

SSO is available on the Business and Enterprise plans -- it is not included on Trial, Basic, Starter, or Pro. Reach out to your account team to configure SSO for your domain.

Next Steps

•Projects & Tenants -- day-to-day project and tenant management, lifecycle states, and best practices.
•Building Multi-Tenant Apps -- how the isolation guarantee works and how to design your own tenant model on top of it.
•Users & Roles -- the full role catalog, custom roles, and account lifecycle.
•Plans & Billing -- current plan tiers, allowances, and pricing.

← PreviousOn-Prem Add-On Packages Next →Plans & Billing

On this page