Skip to main content

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 nametypesemantics
idInt32Unique identifier of the organization. Doesn't change and therefore should be used for data access and filters.
nameStringName 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