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

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 store 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 the 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. Using one of our libraries, you would use the update organization endpoint to create a maximum limit of users in the specified organization. For example, if running a Node backend, it would look something like:

 function updateOrgWithNewPricingInfo(plan, orgId) {
	if (plan === "hobby") {
		auth.updateOrg(orgId, { maxUsers: 1 })
	} else if (plan === "startup") {
		auth.updateOrg(orgId, { maxUsers: 5 })
	} else {
		auth.updateOrg(orgId, { maxUsers: 100000 })
	}
}

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.

For more information on our webhooks, be sure to check out our documentation on the subject.

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. Or, you can enable it for them via your PropelAuth dashboard.

To enable the 2FA requirement setting globally, navigate to your PropelAuth dashboard and then Organization Settings.

Once enabled globally, you can then enable Organizations require 2FA by default to automatically require 2FA for each org. Otherwise, this setting can then be enabled per individual org. Only org owners (or the top level role) can enable this by navigating to the Organizations section of their account page and clicking on Settings.

Here, they have the option to enable/disable this setting as well as a required date for when members of their org need to have 2FA enabled by. If they select Immediately, all users who do not yet have 2FA enabled will be required to set up 2FA before they can continue using your product.

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.

You can also enable the 2FA requirement setting for individual orgs via the PropelAuth dashboard. Head over to the Organizations page, select the org where you want to require 2FA, and click on Settings. From here you can enable/disable the setting as well as when to enforce it.