B2B Multi-Tenant Organizations

The Organizations system enables B2B multi-tenancy in Auris. Each organization represents a customer entity — a company, a team, or any logical grouping — that owns a set of member users, has its own role assignments, and can configure its own enterprise SSO provider. Organizations are independent of each other: a user’s role in Organization A has no bearing on their access in Organization B.

This model is designed for SaaS products that sell to businesses: your single Auris tenant hosts multiple customer organizations, each with isolated membership and access control.

Core Concepts

Organization: A named entity with a unique slug. Organizations have metadata, display names, and settings. They are always owned by exactly one user (the OWNER).

Organization Member: A user who belongs to an organization with one of four roles: OWNER, ADMIN, MEMBER, or VIEWER.

Invitation: A time-limited, token-based invite that allows a user (or an email address not yet registered) to join an organization at a specified role.

Organization-scoped SSO: Each organization can configure its own SAML 2.0 or OIDC identity provider. When a user logs in with an email matching a verified domain, Auris redirects them to their organization’s IdP automatically. See Enterprise SSO.

Creating Organizations

Organizations can be created by any user with the appropriate permission, or programmatically via the Management SDK.

Request body:

{
  "name": "Acme Corporation",
  "displayName": "Acme Corp",
  "slug": "acme-corp",
  "metadata": {
    "plan": "enterprise",
    "contractId": "CNT-2025-0042"
  }
}

Field reference:

Member Roles

Organizations use a four-level hierarchical role system. Higher roles inherit all capabilities of lower roles.

Managing Members

Response:

{
  "data": [
    {
      "userId": "usr_01HX...",
      "email": "[email protected]",
      "firstName": "Alice",
      "lastName": "Rossi",
      "role": "ADMIN",
      "joinedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 }
}

{
  "userId": "usr_01HX...",
  "role": "MEMBER"
}

Invitations

Invitations allow you to add users to an organization by email, even if they do not yet have an Auris account. The invite flow:

1. An ADMIN or OWNER sends an invitation to an email address.
2. Auris generates a unique, time-limited token and sends an email with an accept link.
3. The invitee clicks the link. If they already have an Auris account, they are added to the organization immediately. If not, they are prompted to create an account, after which the invitation is accepted.
4. Invitations expire after 7 days if not accepted.

{
  "email": "[email protected]",
  "role": "MEMBER",
  "message": "You have been invited to join Acme Corp on our platform."
}

Invitation statuses:

SDK Usage

import { useOrganization } from '@auris/react'
 
function OrgDashboard() {
  // Returns the organization context from the authenticated user's session.
  // The organization is derived from the access token's claims.
  const { organization, members, isLoading } = useOrganization()
 
  if (isLoading) return <div>Loading...</div>
  if (!organization) return <div>No organization</div>
 
  return (
    <div>
      <h1>{organization.displayName}</h1>
      <p>Members: {members.length}</p>
      <ul>
        {members.map((member) => (
          <li key={member.userId}>
            {member.email} — {member.role}
          </li>
        ))}
      </ul>
    </div>
  )
}

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'https://auth.yourapp.com',
})
 
const mgmt = auris.createManagementClient({
  clientId: process.env.AURIS_MGMT_CLIENT_ID,
  clientSecret: process.env.AURIS_MGMT_CLIENT_SECRET,
})
 
// List all organizations
const { data: orgs } = await mgmt.organizations.list()
 
// Get a specific organization with its members
const org = await mgmt.organizations.get('org_01HX...')
const { data: members } = await mgmt.organizations.listMembers('org_01HX...')
 
// Create an organization
const newOrg = await mgmt.organizations.create({
  name: 'New Customer Inc',
  slug: 'new-customer',
})
 
// Invite a user
await mgmt.organizations.createInvitation('org_01HX...', {
  email: '[email protected]',
  role: 'ADMIN',
})

import { createServerManagementClient } from '@auris/nextjs/server'
 
// In a Route Handler
export async function GET(
  request: Request,
  { params }: { params: { orgId: string } }
) {
  const mgmt = createServerManagementClient()
  const org = await mgmt.organizations.get(params.orgId)
  const { data: members } = await mgmt.organizations.listMembers(params.orgId)
 
  return Response.json({ org, members })
}

Organization Metadata

Like users, organizations support arbitrary JSON metadata. Use this to store application-specific data alongside the organization record without schema migrations.

{
  "metadata": {
    "plan": "enterprise",
    "contractId": "CNT-2025-0042",
    "maxSeats": 250,
    "billingEmail": "[email protected]",
    "features": ["advanced-analytics", "custom-domains", "audit-export"]
  }
}

Metadata is returned in every organization API response and is accessible in the Management SDK.

Use Cases

SaaS multi-tenancy: Each of your customers is an organization. Your application reads the user’s organization from their JWT or session and scopes all data queries to that organization. New customers are onboarded by creating an organization and inviting their admin.

Enterprise customer onboarding: Create the organization, add the customer’s IT administrator as OWNER, and let them manage their own users and configure their corporate SSO. Your team retains tenant-level visibility via the Admin Console.

White-label solutions: Each end-customer organization can configure their own SSO, domain verification, and display name. The Hosted Login page adapts to per-organization branding when a user’s email matches a verified domain.

Internal product teams: Separate product lines or business units into distinct organizations for isolated role management, without maintaining separate Auris tenant instances.

Required Permissions

Related Pages

• Enterprise SSO per Organization — Configure SAML 2.0 or OIDC SSO for individual organizations
• SCIM 2.0 Provisioning — Automate member sync from an external IdP
• Roles & Permissions — Tenant-level RBAC that complements organization roles
• Console: Organizations — Full Console walkthrough