Users and Organizations

The User object represents an identity that has access to or owns artifacts in an application. A User object may not uniquely identify an individual person, since a person may present themselves as having multiple identities in the same system.

What uniquely identifies a user is their email address, since having access to that email inbox ultimately gives access to all accounts based on that address.

There may be multiple authentication methods on a single user object, such as Email + Password or OAuth. A user can sign in with any of the authentication methods associated with them, as long as those authentication methods are enabled in the WorkOS Dashboard.

Because a user is uniquely identified by their email address, there are no users with duplicate email addresses. WorkOS handles identity linking automatically.

All users will go through an initial email verification process by default.

This applies to all authentication methods, including OAuth and SSO. This unifying interface simplifies how an application considers the authenticity of its users.

If a user’s email domain matches a verified organization domain when signing in with SSO, they will automatically be considered verified and will not need to go through the email verification flow.

Organizations represent both a collection of users that a customer’s IT admin has control over and a workspace within which members collaborate. Organizations are a first-class concept in WorkOS and support a suite of features around organizational management. There is no limit to the number of organizations that can be created in WorkOS.

An organization contains users as members. Organization membership allows organizations to be modeled as “workspaces,” with users’ access to them represented through memberships.

WorkOS organization memberships are designed to be flexible and support any B2B app model. For example:

• Multiple Workspaces: A self-serve productivity app, like Figma, where each user can be in any number of organizations, can create their own workspace and join any number of other workspaces.
• Single Workspace: An app that has no collaboration outside a customer’s company, like an employee survey tool, where each user is in exactly one organization.

While these are two distinct models, the choice may depend on the go-to-market strategy, which may change over time. WorkOS AuthKit supports both.

It is common for users to create resources in B2B applications. The organization serves as a container for these resources, so that access is dependent on a user’s membership in the organization.

This means when a user leaves an organization and is no longer a member, the data remains with the organization and not the user. Organizations provide the level of data ownership that B2B applications structure around.

While organization membership conveys the most basic form of access, more granular role information can be attached per member within the application’s own database.

In addition to the environment-level roles, organizations can define their own custom roles, which are assignable only within the context of the organization. Refer to the organization roles documentation for more details.

Applications that use a soft-delete model can utilize the extended organization membership lifecycle. Organization memberships have three possible statuses:

• pending, when a user is invited to an organization
• active, when a user is added as an organization member or accepts an invitation
• inactive, when an organization membership is deactivated

For soft-delete use cases, we also provide deactivation and reactivation APIs:

• Deactivating an organization membership sets its status to inactive and revokes all active sessions. Note pending memberships cannot be deactivated and should be deleted using the deleting membership API instead.
• Reactivating an organization membership sets its status to active and retains the role attached to the organization membership prior to deactivation. This role can be updated using the update organization membership API. Note pending memberships cannot be reactivated. For this the user should go through the invitation acceptance flow instead. If invitations are not needed, the organization membership can be created as active directly.

Applications that use a hard-delete model can use organization memberships without deactivation/reactivation by deleting memberships for users who should no longer have access to an organization.

Hard deletion is preferred when the application has no need to “remember” the membership. For example, when members operate solely on customer data and have no data of their own, there is no need to retain their membership data after they leave. An application in this case may even want to entirely delete the User once the membership is deleted.

Deactivation is preferred in cases where a member retains some data after leaving the organization – for example, messages, documents, or other data that reference that member. It also enables building a user interface to list former members, perhaps with the option to reactivate them.

Beyond manually adding or removing users to and from organizations as members, users can be automatically Just-in-Time (JIT) provisioned into an organization if their email address matches one of the organization’s verified domains. This allows customers to quickly onboard teammates.

Users can also invite individuals to organizations, regardless of their email domain. This is handy for contractors within a company, or a collection of people without a shared domain.

In some applications, all activity should happen within the context of an organization. This pattern is common in B2B applications where:

• All features and data are scoped to an organization
• Users need to be associated with an organization to use the application

For these applications, when new users do not already belong to an organization via Just-in-Time provisioning or an invitation, an organization needs to be created for them.

To ensure all users have at least one organization, the following steps apply:

1. Check the access token: When AuthKit redirects a user to the application after signup or sign-in, the access token should be checked for an org_id
2. Present organization creation form: If no organization is present, the user is shown a form with a name field to create a new organization
3. Create the organization: On form submission, the create organization API creates the organization
4. Create organization membership: The create organization membership API adds the user as a member of the new organization
5. Refresh the token: The authenticate with refresh token API is called with the new organization ID to receive a new access token that includes the organization