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. While this can be disabled in the WorkOS Dashboard, we recommend keeping it enabled so that any user object you get back from an authentication request is guaranteed to have a verified email address.

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, 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.

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:

While these are two distinct models, your choice may depend on your go-to-market strategy, which may change over time. WorkOS User Management 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:

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

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.