Organizations - Built-in Entity
Nile is a natively multi-tenant platform. The built-in entity "organization" represents a tenant of your SaaS control plane.
How Organizations are used in Nile
Nile expects every user to belong to one or more organizations.
Users can create organizations and they automatically belong to the organization they created. As a developer you can also create organizations for users, either manually from Nile Dashboard or programmatically when a user signs up to your Nile-based SaaS.
Users that belong to an organization can add other users from the same workspace to this organization. As a developer you can also add any user to any organization within your workspace.
All the interactions between users and custom entities are within the context of an organization. Nile automatically enforces access, so a logged in user can only read or modify entity instances that belongs to organizations that they are a member of.
Example
We'll use the same scenario as the Quickstart. As a reminder, you are building a control plane for an imaginary company called Clustify
that allows users to manage MySQL clusters. The only custom entity in that scenario is clusters
.
Let's say that Shaun signed up to Clustify
and created an organization called Managed Expenses
. His colleague Mary also signs up to Clustify
and creates an organization called side project
. Because both Shaun and Mary are users in Clustify
, Shaun can add Mary to Managed Expenses
organization.
Shaun creates a cluster called MyFirstCluster
and does so in the Managed Expenses
organization. Mary will be able to see this cluster and edit its configuration. The cluster is owned by the organization, and all members can see and modify it. Similarly, when Mary creates a new cluster called dev
in Managed Expenses
organization. Shaun will be able to manage it.
Now let's say Mary creates a new cluster called toy
in side project
. Because toy
belongs to a different organization, Shaun doesn't even know it exists and has no way to access it.
This permission and access model is entirely enforced by Nile, and your control plane will have it out of the box.
Schema
The organization entity has the following fields:
field name | type | semantics |
---|---|---|
id | Int32 | Unique identifier of the organization. Doesn't change and therefore should be used for data access and filters. |
name | String | Name of the organization. Users can modify the organization name. |
Those fields are in addition to the default fields that exist for all Nile entities.
APIs
Here are some examples of how to use the organizations entity. See the API Reference for full documentation of Nile's REST APIs and JS SDK.
List all organizations
When authenticated as a user (i.e with user's token), this will list all organizations that the user is a member of. When authenticated as a developer, this will list all the organizations that were created in the workspace.
curl -X GET "https://prod.thenile.dev/workspaces/$NILE_WORKSPACE/orgs" --header "Authorization: Bearer $TOKEN"
Create organization
curl -X POST "https://prod.thenile.dev/workspaces/$NILE_WORKSPACE/orgs" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "my_new_startup"
}'
Add user to an organization
The user is added with organization-specific metadata. The role of the user in this specific organization is an editor.
curl -X POST "https://prod.thenile.dev/workspaces/$NILE_WORKSPACE/orgs/$ORG_ID/users" \
--header "Authorization: Bearer $INVITER_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "gwen@demo.io",
"metadata": {"role":"editor"}
}'
List all users in an organization
curl "https://prod.thenile.dev/workspaces/$NILE_WORKSPACE/orgs/$ORG_ID/users" -H 'Authorization: Bearer eyJhbGci...'
Events
TBD
Metrics
TBD