Skip to main content

Organizations

Organizations let you model multi-organization structures within a single tenant. This is useful when your product serves multiple companies, teams, or departments — each with their own members and roles — while sharing a common tenant configuration.

What Are Organizations?​

An organization is a named group within your tenant. Each user can belong to one or more organizations, and each organization can have its own members and role assignments.

Common use cases:

Use CaseExample
B2B SaaSEach customer company gets its own organization
Enterprise appDifferent departments (Engineering, Finance, Sales)
Multi-workspaceEach project or workspace is modeled as an organization

Managing Organizations​

Portal​

Navigate to /t/{tenantSlug}/portal/organizations to:

  • Create a new organization
  • View organization members and their roles
  • Manage invitations — invite users to join an organization
  • Assign roles — define which organization role each member holds

Creating an Organization​

  1. Go to /t/{tenantSlug}/portal/organizations
  2. Click New Organization
  3. Enter a name and optional description
  4. Click Create

Members​

Each organization has a list of members. A member is a tenant user with an assigned role within the organization.

Adding Members​

  1. Open the organization in the portal
  2. Click Add Member
  3. Search for a user by name or email
  4. Assign an organization role
  5. Click Add

Updating a Member's Role​

  1. Open the organization
  2. Find the member in the list
  3. Click the role dropdown and pick a new role

Removing Members​

Click the Remove button next to a member to remove them from the organization. Their tenant account and roles are not affected.

Organization Roles​

Organization roles are separate from tenant-level roles. They are scoped to a specific organization and can be used to represent position or permissions within that organization (e.g., Admin, Member, Viewer).

Defining Organization Roles​

  1. Go to /t/{tenantSlug}/portal/organizations
  2. Open an organization
  3. Go to the Roles tab
  4. Click Add Role and give it a name

You can then assign that role to any member of the organization.

Using organization roles in authorization

Organization membership and roles are included in access tokens as claims. Your application can read these claims to make authorization decisions based on a user's organization context.

Inviting Users to an Organization​

You can invite users who are not yet members of your tenant to join an organization.

Sending an Invitation​

  1. Go to the organization in the portal
  2. Click Invite Member
  3. Enter the user's email address
  4. Select the role they will receive on joining
  5. Click Send Invitation

The invited user receives an email with a link. When they click it, they are prompted to register (if they don't have an account) or log in, and are then added as an organization member.

Managing Invitations​

In the organization's Invitations tab you can:

  • View all pending invitations and their expiry
  • Resend an invitation that was not received
  • Revoke a pending invitation

User Self-Service​

Users can view their own organization memberships from their account page:

  1. Navigate to /account/organizations
  2. See all organizations they belong to, along with their role in each

API Access​

The full organization lifecycle is available via the Admin API:

OperationEndpoint
List organizationsGET /t/{tenantSlug}/api/v1/admin/organizations
Create organizationPOST /t/{tenantSlug}/api/v1/admin/organizations
Get organizationGET /t/{tenantSlug}/api/v1/admin/organizations/{orgId}
Update organizationPUT /t/{tenantSlug}/api/v1/admin/organizations/{orgId}
Delete organizationDELETE /t/{tenantSlug}/api/v1/admin/organizations/{orgId}
List membersGET /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/members
Add memberPOST /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/members
Remove memberDELETE /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/members/{userId}
List org rolesGET /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/roles
Create invitationPOST /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/invitations
Revoke invitationDELETE /t/{tenantSlug}/api/v1/admin/organizations/{orgId}/invitations/{id}