Skip to main content

Setup

There are two ways to use organizations, and the theauth.org object used in the examples below only exists with the first one.
Isometric diagram of an identity provider connected by SAML 2.0 or OIDC and a SCIM 2.0 directory both feed an organization that holds members and agents, with tenant tagging.

An identity provider and a SCIM directory feed an organization that holds members and agents.

Programmatic API (theauth.org). Pass an org config object to createTheAuth. Without it, theauth.org is null and every theauth.org.* call below fails.
HTTP endpoints (organization plugin). The organization() plugin registers /auth/org/* routes for an adapter to serve. It does not add theauth.org to the instance.
The plugin routes act on the authenticated user, resolved from auth.adapter or an auth.session token. The code samples below call theauth.org!.<method>(...). They assume the org config was passed. Use ?. instead of ! if you want to tolerate it being absent.

Creating organizations

The creator is automatically added as a member with the owner role.

Inviting members

Accept on the invited user’s side:

Managing members

Roles and permissions

Four built-in roles ship by default: Check permissions at runtime:

Custom roles

Set allowCustomRoles: false in the org config (or the plugin options) to restrict orgs to the built-in roles only.

Configuration reference

OrgRole[]
Roles created for new organizations. Defaults to the four built-in roles.
number
default:100
Maximum members per organization.
number
default:5
Maximum organizations a user can create.
boolean
default:true
Whether createRole is allowed.
number
default:604800000
Invitation lifetime in milliseconds (7 days).
number
default:50
Maximum invitations per organization per hour.

Endpoints

organization() plugin

All plugin routes require an authenticated user.

theauth.org.handleRequest (module)

The module’s own handler serves a larger set of paths. It does no authentication, so only mount it behind your own checks.

SSO

Enterprise SSO connections scoped to an organization.

SCIM

Automated user and group sync from your identity provider.

Admin

Cross-organization user management tools.

Permissions

Scoped permissions that integrate with org membership.
Last modified on October 18, 2026