Organizations

Organizations enable you to group users and apply specific configurations, branding, and access controls to them. Organizations are useful for B2B applications where you serve multiple customer companies.

What is an Organization?

An organization represents a group of users within a tenant, typically corresponding to a customer company in a B2B application.

Each organization can have:

• Its own set of members (users)
• Organization-specific roles and permissions
• Custom branding and configuration
• Isolated access controls

When users authenticate with an organization context, the resulting tokens include an org_id claim that your API can use to enforce organization-level authorization.

Use Cases

B2B SaaS Applications

Tenant: your-saas-product
├── Organization: company-a
│   ├── Users: company-a's employees
│   └── Roles: admin, member, viewer
├── Organization: company-b
│   ├── Users: company-b's employees
│   └── Roles: admin, member
└── Organization: company-c
    ├── Users: company-c's employees
    └── Roles: admin, member, viewer, auditor

Team-Based Access Control

Provide different teams within a company with isolated access:

Organization: engineering-team
Organization: sales-team
Organization: support-team

Organization Invitations

Organization invitations provide a streamlined way to onboard new users to an organization. When you create an invitation, you can:

• Pre-configure user attributes: Set roles, app metadata, and user metadata before the user accepts
• Control the connection: Specify which authentication method the user should use
• Set expiration: Invitations expire after a configurable time period (default: 7 days, max: 30 days)
• Track the inviter: Record who sent the invitation for auditing purposes

Invitation Flow

1. An admin creates an invitation through the Management API
2. An invitation URL is generated with a unique ticket
3. The invitee receives the invitation (optionally via email)
4. The invitee clicks the invitation URL and completes the signup/login flow
5. Upon completion, the user is automatically added to the organization with the pre-configured settings

Invitation Properties

• inviter: Information about who sent the invitation
• invitee: Email address of the person being invited
• client_id: The application the user will access
• connection_id: Optional specific authentication connection
• roles: Role IDs to assign to the user
• app_metadata / user_metadata: Custom data to attach to the user
• ttl_sec: Time-to-live in seconds before the invitation expires
• send_invitation_email: Whether to automatically send an invitation email

Organization Switching

Users who belong to multiple organizations can switch between them without re-authenticating by passing the organization parameter in a refresh token grant:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=CLIENT_ID&
organization=target-org

The organization parameter accepts either an organization ID or name. The user must be a member of the target organization. The resulting tokens will include the new organization's org_id and org_name claims.

If no organization parameter is provided during a refresh, the original organization from the login session is automatically preserved.

See Authentication Flow and Tokens for more details.

Organization Roles and Permissions

Organizations support role-based access control (RBAC) to manage user permissions within the organization context.

Permission Inheritance

By default, user permissions are scoped to organizations. However, tenants can enable the inherit_global_permissions_in_organizations flag to allow users with tenant-level roles to inherit those permissions in all organizations.

See Tenants and Security Model for more details.

Access to every organization

Normally a user can only get an organization token (the organization parameter at /authorize or /oauth/token) for an organization they are a member of. Two Management API permissions (on urn:authhero:management) let a user skip that check. Both only count when assigned at global scope, directly or through a role. An assignment inside an organization never bypasses membership.

	access:all_organizations	admin:organizations
Org tokens without membership	Yes	Only with the inherit_global_permissions_in_organizations tenant flag
Lists every org via GET /api/v2/organizations	Yes	Only with read:organizations
Tenant admin on the multi-tenancy /tenants routes	No	Yes
Registers DCR clients on any child tenant	Only with create:clients from a global role	Yes

Use access:all_organizations for support or back-office staff who need to open any organization with the scopes of a global role, but must not administer tenants. Global roles are always merged into organization tokens, so the org token carries the role's permissions for the requested audience. The permission itself never appears in app-audience tokens.

GET /api/v2/users/{id}/organizations still returns memberships only, as in Auth0. To list every organization, call GET /api/v2/organizations with a global Management API token that carries access:all_organizations or read:organizations. The new permission only opens the list route. It is ignored on org-scoped tokens and does not open organization details, members or invitations.

API Reference

• GET /api/v2/organizations
• POST /api/v2/organizations
• PATCH /api/v2/organizations/:id
• DELETE /api/v2/organizations/:id
• POST /api/v2/organizations/:id/invitations
• GET /api/v2/organizations/:id/members
• POST /api/v2/organizations/:id/members