FerriskeyOrganizations
Organizations are a B2B grouping layer inside a realm. One realm holds many organizations, a user can belong to several at once, each organization carries custom key-value metadata, and members can be given roles scoped to the organization. That covers the usual multi-tenant SaaS shape: customers are organizations, users are members.
New to B2B identity?
For conceptual background on how customer-facing (B2B/CIAM) identity differs from workforce IAM, see What is CIAM? and Branding, Portals & Org Policies in the Learn section.
Why organizations?
Realms isolate at the deployment level, one per product or per environment. Organizations sit a level below. They let you model your customers’ business structure without spinning up a realm per customer.
Use organizations when:
- Your users belong to customer accounts that have distinct identities (company name, billing plan, external IDs).
- You need to list every organization a given user belongs to, or every member of a given organization.
- You want to attach arbitrary metadata to a customer account (CRM ID, subscription tier, feature flags) without extending the user schema.
Use a separate realm per tenant instead when you need complete credential isolation, different authentication policies, or different token lifetimes per tenant.
Organization fields
| Field | Type | Required | Description |
|---|---|---|---|
id | UUID v7 | generated | Identifier |
realm_id | UUID | generated | The realm this organization belongs to |
name | String (1 to 255) | Yes | Human-readable label |
alias | String (1 to 255) | Yes | URL-safe identifier: lowercase alphanumeric, -, and _. Unique per realm |
domain | String (up to 255) | No | Email domain. Stored and validated, but not yet used for automatic onboarding. See the roadmap below |
redirect_url | String | No | Callback URL |
description | String | No | Free-text description |
enabled | Boolean | No | Defaults to true. A disabled organization rejects new member additions |
created_at | DateTime (UTC) | generated | Creation timestamp |
updated_at | DateTime (UTC) | generated | Last-modified timestamp |
Realm scoping
Every organization belongs to exactly one realm. All API endpoints are realm-scoped:
/realms/{realm_name}/organizationsA user and the organization they join must be in the same realm. Cross-realm membership is rejected.
The alias must be unique within the realm. Attempting to create or update an organization with a duplicate alias returns a AlreadyExists error.
The enabled flag
Setting enabled: false freezes membership additions: POST /members starts rejecting requests. Existing members are left alone. It is how you suspend a customer without deleting the organization or emptying it.
Permissions
| Action | Required permission |
|---|---|
| List, view organization | ManageRealm or ManageUsers or ViewUsers |
| Create, update organization | ManageRealm or ManageUsers |
| Manage members and attributes | ManageRealm or ManageUsers |
| Delete organization | ManageRealm only |
There are no organization-specific permissions. All access control uses the realm-level permissions above.
Roadmap
Still missing:
- Domain-based auto-onboarding. The
domainfield is stored and validated, but nothing assigns users to an organization from their email domain yet. - Organization policies. Forced SSO, domain-matching rules, and org-level authentication policies are not shipped.
- Soft delete. Deletes are permanent, with no archive or restore.
Organizations or separate realms?
| Scenario | Recommendation |
|---|---|
| B2B SaaS, customers share auth policies | Organizations within one realm |
| Customers need completely different token lifetimes or IdP federation | Separate realms per customer |
| Internal multi-team product | Organizations within one realm |
| Regulated multi-tenant isolation (data residency) | Separate realms |