Users and Organizations

The User object represents an identity that has access or owns artifacts in your 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 you have enabled those authentication methods in the WorkOS Dashboard.

Because a user is uniquely identified by their email address, you won’t have 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 your application considers the authenticity of your 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 your 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 you can create in WorkOS.

An organization contains users as members. Organization membership allows you to model organizations as “workspaces” and user’s access to them with 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, your choice may depend on your go-to-market strategy, which may change over time. WorkOS AuthKit supports both.

It’s common for users to create resources in B2B applications. You can use the organization as a container for these resources, so that access is dependent on a user’s access to 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, you can attach more granular role information per member within your own application’s 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.

If your application uses a soft-delete model, you 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.

If your application uses a hard-delete model, you may use organization memberships without deactivation/reactivation by deleting memberships for users who should no longer have access to an organization.

Hard deletion is preferred if the app has no need to “remember” the membership. For example, when members operate solely on customer data and have no data of their own. When a member of the organization is gone, there’s no need to keep around their membership data. An app in this case may even want to entirely delete the User once the membership is deleted.

Deactivation may be preferred in cases where a member retains some data after leaving the organization, for example: messages, documents, or other data which reference that member. It also allows for 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.