Organizations

Organizations are groups of your users that will use your product together. These are also referred to as companies, tenants, teams, workspaces, or shared accounts. Let’s say you are building a product that helps people create and share documents internally. Your customers might include:

• A two-person startup
• A fast-growing 50-person tech company
• A hobbyist using you by themselves, but who might get more employees someday
• A large enterprise

Each of these would be an organization within your product, managed by PropelAuth.

Configuration & Settings

The following options are available on the Organization Settings page in your PropelAuth dashboard.

Changing the word "Organization"

If you use a different word for organizations (maybe team, company, tenant, workspace, group, or something domain specific), you can configure this by changing the organization meta-name in the Organization Settings page in your PropelAuth dashboard.

Changing your organization meta-name will update the word "Organization" in the hosted pages as well, such as the create org page.

Users can create their own organizations

If enabled, users have access to the 'Create Org' UI, allowing them to create their own organizations. Disable this if you want to manually create organizations yourself, on behalf of your users.

All users must be in an organization

This setting will make sure that all users must be in at least one organization before they are allowed to use your product. The signup/login flows will direct the user to create or join an organization.

Maximum number of orgs per user

This sets the limit on the number of organizations a user can be in at once. Most commonly, we see people setting this to either 1 (meaning each user can only be in one organization) or "as many as they want."

Creating Orgs

There are three ways to create an organization.

1. Your end users can create them themselves via the hosted pages. Just like the signup and login pages, PropelAuth provides a UI for your end users to create these organizations. Our frontend libraries provide functions for you to redirect your users to the "create org" page and to get which orgs the user is a member of.

2. You can use the PropelAuth dashboard to create organizations for your users.

3. You can use our APIs to create organizations programmatically.

Organization Domains

An optional field for each organization is the Organization Domain. If you set this field, you can limit access to the organization by only allowing users with an email address that matches the set domain. If an organization has users from multiple domains, you can add additional domains in the Organization Domain field.

Organization Metadata

Organization Metadata is an optional JSON field that stores information specific to an organization. It can be updated either via the Update Org API or in the PropelAuth Dashboard. You can retrieve this data in several ways, such as through the backend API, when validating an access token, or in the OrgMemberInfo class in our frontend libraries.

Adding Users to Orgs

PropelAuth provides a management UI for your users as well. This enables them to send invitations, manage roles, remove users from the organization, and more. A user that received an invitation will be prompted to sign up if they haven't yet. Afterwards, they can accept or decline the invitation.

Your users can also allow anyone with a matching email domain to automatically join at the lowest role (e.g. everyone from @acme.com can join the Acme Organization).

We also support SAML which enables your customers to connect their organization membership directly to their identity provider (like Okta, OneLogin, or JumpCloud).

Setting a Maximum User Limit per Org

Let's say you have a pricing model that has three tiers and plans

• Hobbyist, meaning team size is max 1
• Startup, meaning team size is max 5
• Growth, meaning unlimited team size

When an organization selects a plan, you will want to set a limit based on the plan they are paying for. To do this, you will want to update the organization they are a part of programmatically.

Connecting Orgs to a Payment System

In order to properly accomplish this kind of pricing limitation, you need a mapping from your organization to a payment system, like Stripe. If you want to do this programmatically, you can use our webhooks and listen to the org.created event.

Enable 2FA for Organizations

Organizations can enhance security by requiring two-factor authentication (2FA) for their members. Enabling this setting has two parts - first by enabling it globally in your PropelAuth dashboard and then enabling it per organization. Turning this setting on globally allows your organizations to enable 2FA requirements themselves by adding a setting to the hosted pages.

If the org owner selects a grace period to allow 2FA setup, all users in their org will receive an email instructing them to enable 2FA by navigating to their account page. If they do not have 2FA setup by the time the grace period has ended, they will not be able to continue using your product until they have it setup.

Isolated Organizations

Isolated organizations are an advanced feature. By default, users in your project can belong to multiple organizations with one single account. However, some customers may require stronger isolation guarantees than that, which is where “isolated organizations” come in. The key difference between an isolated organization and a regular organization is that the users in an isolated organization are completely separate from the rest of your users.

When would I need isolated orgs?

One use case where isolated orgs is important is if you have multiple organizations with overlapping users, but you need to treat the users as separate.

Converting to an Isolated Organization

You can convert an org to isolated by navigating to the org's page in the PropelAuth Dashboard and clicking on Convert. Alternatively, you can use the Migrate Org to Isolated API.

Multiple User Accounts

One of the key features of Isolated Orgs is separate user accounts for each isolated organization. For example, a user with the email "example@acmeinc.com" can have different accounts for each isolated org that they belong to, as well as an account for all non-isolated orgs - all with unique user IDs and user properties.

Requirements and Restrictions

There are a few requirements and restrictions to consider before converting an organization to an isolated one:

• Members of the organization must login via Enterprise SSO. Other login methods such as email/password and magic links are not compatible.

• Org invites are not supported. Users can only be added to the organization by being provisioned in the organization's IdP (Okta, Entra, etc.)

• Internal roles are not supported.

• Members of the Isolated Org can only belong to that one org. They will not be allowed to join other organizations. However, they can create a different account with the same email address to join other organizations.

• Since users can now have multiple accounts with one email address, API requests such as Fetch User by Email will behave a bit differently. If an Isolated Org ID is not included in the request, only users who do not belong to an isolated org will be returned.