About Organizations
Organizations are sub-divisions within your application that can be accessed by your end users.
On Userfront, these sub-divisions of your application are called tenants, and an organization is a tenant that has 2 or more users.
Organizations enable you to allow multiple users to access a tenant, with specific levels of access for each user.
You can create organizations and invite users through the dashboard or API, with custom roles, access levels, and authentication for each organization as desired.
Organization Requirements
Tenants come in 3 flavors: Individual, Organization, and Enterprise org.
Individual and Organization tenants work the same; the only difference is in the number of users with a role in the tenant.
Tenant type
Description
A tenant will be labelled as “Individual” when it has 1 user and “Organization” when it has 2 or more users. In both cases, it is still called a tenant.
Tenant nesting
See also Tenant Nesting
Tenants can also be nested multiple levels deep. This is referred to as nested multi-tenancy.
With nested multi-tenancy, you can create organizations and sub-organizations within your application. Userfront has the ability to further nest tenants as many layers deep as your needs require.
To use roles and tenants on Userfront, create and manage your roles, tenants, and users from the dashboard or API.
Machine-to-machine authorization
See also Machine-to-machine auth
You can scope your Userfront tenants to model devices or groups of devices in your network, allowing for fine-grained machine-to-machine authentication and authorization.
Each tenant on Userfront can have its own individual access levels, roles, API keys, and authentication settings.
Organization Handling
Individuals vs Organizations
On Userfront, you can handle individual (single-user) tenants the same way as organization (multi-user) tenants from day 1. This allows you to build your application for scale without having to re-architect your systems as you go.
Userfront can automatically create an individual tenant for each user when they register for your service, and assign them a default role in their tenant (typically “admin”).
You can store account-level information, such as “business type”, within the tenant’s data object, and person-level information, such as “role at company” within the user’s data object.
This architecture scales from early products with only a few users up to enterprise organizations with thousands of users in each tenant.
Authorization object
When a user has a role in one or more tenant, it will show in their authorization object.
This authorization object is included in their JWT access token by default, and can also be obtained via the /self API endpoint.
{
"email": "bgates@example.com",
...
"authorization": {
"wbmxvmvn": {
"tenantId": "wbmxvmvn",
"name": "Organization A",
"roles": ["contributor","support"]
},
"qbjxdgxb": {
"tenantId": "qbjxdgxb",
"name": "Sub-org B1",
"roles": ["admin"]
}
}
}Tenant data object
You can store JSON data on each tenant, including nested tenants, using the tenant.data object. For example, a tenant lookup could return something like this:
{
"mode": "live",
"tenantId": "wbmxvmvn",
"name": "Organization A",
"createdAt": "2024-08-07T13:19:40.327Z",
"updatedAt": "2024-08-09T17:04:39.628Z",
"lastActiveAt": "2024-08-09T16:34:27.789Z",
...
"data": {
"company_size": "250-1000",
"industry": "Food & beverage",
"requested_assistance": true,
"referer": "site.com/page",
}
}
