B2B Organizations (soft grouping inside a Tenant)

The Organizations system enables soft B2B grouping inside a single Auris Tenant. Each organization represents a team, department, or logical grouping within that tenant — with its own members, roles, and optional enterprise SSO. Organizations are independent of each other: a user’s role in Organization A has no bearing on their access in Organization B.

Use Organizations for teams inside one customer’s Tenant. Use Create Tenant when onboarding a new external customer that needs a hard data boundary.

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