Tenants, users & memberships
Zynth Auth's model has three core entities.
User
A global identity — a person (or service/agent identity) with an email and credentials. A user exists once, independent of any organization, and can belong to several organizations.
Populations
Every user belongs to one population, fixed when the account is created and never changed (someone who needs both uses two separate accounts):
workforce— employees, admins, internal staff. The default for organization sign-up.customer— end users / consumer identities (CIAM).
Populations share the same core and token infrastructure but differ in policy:
| Workforce | Customer (CIAM) | |
|---|---|---|
| Created by | During the private beta: an invitation (a beta invite presented at the agent bootstrap door, or an organization provisioned for you by the operator — public sign-up answers 403); otherwise organization sign-up; admin invite; verified-domain auto-join; an AI agent's onboarding bootstrap (which creates the tenant and its owner together) | Self-sign-up, social login, or magic link |
| Refresh-token lifetime | 7 days | 30 days (frictionless sessions) |
| Baseline permissions | member (self-service + more) | identity:read + identity:self:write — and nothing else. The second one is what carries the data subject's own rights (consent, GDPR Art. 15/17 requests); it is deliberately not an admin permission. |
| Admin roles | Can be granted | Cannot be granted (blast radius stays minimal) |
GET /api/v1/me exposes the caller's population (and email_verified) so your app can
branch on it.
Customer self-sign-up
Customer sign-in methods that can create a new account — self-sign-up,
social login, and (for existing users)
magic links — only provision new users into an
organization that has explicitly opted in. This is a per-tenant setting
(ciam_signup_enabled, default off), toggled by a tenant owner/admin in the console under
Organization settings (or via tenant settings),
and is fail-closed:
until an organization enables it, customer self-sign-up returns a generic 403 (identical
for an unknown organization — no enumeration). Workforce accounts are always created by an
admin, never by self-sign-up.
Tenant (organization)
A tenant is an organization or workspace that owns users' access. It has a unique
slug (used at login) derived from its name. Sign-up creates one and makes the creator
its owner.
Isolation
Each tenant has an isolation strategy that determines where its data lives:
pooled— shares infrastructure with other tenants, kept apart by two independent boundaries: an always-scoped data-access layer and PostgreSQL row-level security beneath it, both derived from one source of truth and fail-closed. A cross-tenant leak would take two independent failures, not one bug. Details for a security review: Security & tenant isolation.dedicated— reserved for a single-tenant tier with its own database, which is designed for and not yet built. No organization holds this value today: every organization ispooled.
This is set when the organization is provisioned; your integration reads it (e.g. from
/api/v1/me) but doesn't choose it per request.
Membership
A membership links a user to a tenant with a role (e.g. owner, member) and an
is_owner flag. A user has at most one membership per tenant.
Roles and permissions are resolved server-side, from the database — never trusted from the token. On every authenticated request Zynth Auth re-validates the membership, so removing a user's access takes effect immediately, not at the next token expiry.
How they fit together
Next
- Tokens & sessions — what a token carries and how sessions work.
- API reference.