Organizations And SSO¶

Organizations let tenants model teams, companies, departments, customer accounts, and shared administration. Use organizations when access is managed by a business relationship instead of individual self-service alone.

Organization model¶

Object	Purpose
Organization	Shared account or business unit inside a tenant
Member	User assigned to the organization
Role	Permission set for organization or tenant actions
Invitation	Pending request to join
Verified domain	Domain proof used for routing, trust, or auto-join
SSO provider	Enterprise OIDC configuration for sign-in
Active organization	Organization context selected for the current session

When to create an organization¶

Create an organization when:

multiple users share access to the same workspace, account, or customer data
a customer expects a company-owned login policy
SSO or domain routing should apply to a subset of users
audit logs need to show business-account context
roles differ between personal access and organization access

Avoid organizations when a tenant has only individual accounts and no shared administration, billing, SSO, or access boundary.

Organization lifecycle¶

Create the organization.
Assign an owner or administrator.
Add members manually or through invitations.
Verify one or more domains.
Configure enterprise SSO when the customer identity provider should control sign-in.
Map organization roles to application permissions.
Review member activity and access changes.
Transfer ownership or delete the organization when the business account changes.

Enterprise SSO¶

Use enterprise SSO when a customer's identity provider should control login. Typical providers include Okta, Microsoft Entra ID, Google Workspace, and other OIDC-compatible systems.

Setup flow:

Create or select an organization.
Add the provider issuer, authorization endpoint, token endpoint, UserInfo endpoint, and JWKS URI.
Add client credentials from the provider.
Configure redirect URIs in the provider.
Verify the organization email domain.
Test login with a non-admin user.
Map identity-provider claims or groups to organization roles.
Enable routing or enforcement for the organization.

Test before enforcement

Always test SSO with a non-admin user before enforcing it. Keep at least one break-glass administrator who can recover access if the provider is misconfigured.

Domain verification¶

Verified domains help route users to the correct organization and can support auto-join behavior.

Recommended domain workflow:

Add the domain to the organization.
Prove control through the supported verification method.
Wait until the domain is verified.
Enable routing.
Enable auto-join only after roles and restrictions are clear.

Do not enable automatic membership solely because a user has an email address on the domain. Consider contractors, shared inboxes, aliases, alumni, and forwarding rules.

Role design¶

Keep organization roles understandable:

Role	Typical permissions
Owner	Full organization administration, ownership transfer, deletion
Admin	Member management, SSO settings, domain settings
Member	Product access without administration

Map roles to scopes and policies rather than hard-coding role names in every application.

SCIM and directory sync¶

SCIM can create, update, suspend, and remove organization memberships from an enterprise directory. Treat directory sync as authoritative only after testing the full lifecycle.

Validate:

user creation
profile update
group or role update
user suspension
user reactivation
user removal
duplicate email handling
behavior when the directory is temporarily unavailable

Directory deprovisioning should remove or suspend access promptly. It should not delete audit records.

API surface¶

Organization administration uses tenant-scoped routes.

Route	Purpose
`GET /api/v1/organizations`	List organizations visible to the caller
`POST /api/v1/organizations`	Create an organization
`GET /api/v1/organizations/{id}`	Read organization details
`PUT /api/v1/organizations/{id}`	Update organization details
`DELETE /api/v1/organizations/{id}`	Delete an organization
`GET /api/v1/organizations/{id}/members`	List members
`POST /api/v1/organizations/{id}/members`	Add a member
`DELETE /api/v1/organizations/{id}/members/{user_id}`	Remove a member
`PATCH /api/v1/organizations/{id}/members/{user_id}/role`	Change a member role
`POST /api/v1/organizations/switch`	Switch active organization context
`POST /api/v1/organizations/{id}/transfer-ownership`	Transfer organization ownership
`GET /api/v1/organizations/{org_id}/domains`	List verified or pending domains
`POST /api/v1/organizations/{org_id}/domains`	Add a domain
`POST /api/v1/organizations/{org_id}/domains/{id}/verify`	Start verification
`GET /api/v1/organizations/{org_id}/domains/{id}`	Get domain details
`PATCH /api/v1/organizations/{org_id}/domains/{id}`	Update domain settings (auto-join toggle, auto-join role)
`DELETE /api/v1/organizations/{org_id}/domains/{id}`	Remove a domain
`POST /api/v1/organizations/{org_id}/domains/{id}/confirm`	Confirm verification
`GET /api/v1/organizations/{org_id}/invitations`	List invitations
`POST /api/v1/organizations/{org_id}/invitations`	Create an invitation
`POST /api/v1/organizations/{org_id}/invitations/bulk`	Bulk create invitations (up to 50)
`DELETE /api/v1/organizations/{org_id}/invitations/{id}`	Revoke an invitation
`GET /api/v1/organizations/{org_id}/sso-provider`	Read SSO configuration
`PUT /api/v1/organizations/{org_id}/sso-provider`	Create or replace SSO configuration
`DELETE /api/v1/organizations/{org_id}/sso-provider`	Remove SSO configuration

Administration checklist¶

Keep at least two trusted administrators.
Require MFA for owners and administrators.
Verify domains before SSO routing or auto-join.
Keep break-glass access outside the enforced SSO path.
Audit role assignments and ownership transfers.
Test deprovisioning before relying on directory sync.
Review SSO configuration after identity-provider changes.
Monitor failed SSO logins during rollout.