Tenants

The Tenants module provides methods to create, fetch, update, delete, and interact with tenants that the currently authenticated user is a member of. Each user may belong to multiple tenants, and most operations automatically default to the currently selected tenant. You can explicitly override this by providing a tenant ID to most methods.

Most methods assume the current user is authenticated. If not, a 401 Unauthorized error will be returned.

Setting the Current Tenant

You can manually set the current tenant using await nile.withContext({ tenantId }). withContext returns a copy of the nile instance with a context that captures what was passed. It also accepts a second parameter for convenience for multiple requests.

Returns a nile with the context

const nileWithContext = await nile.withContext({
  tenantId: '019612d7-56e7-7e87-8f30-ad6b05d85645',
});

Self contained callback

const [currentUser, listOfTenantUsers] = await nile.withContext(
  {
    tenantId: '019612d7-56e7-7e87-8f30-ad6b05d85645',
  },
  async (_nile) => Promise.all([_nile.users.getSelf, _nile.users.list]),
);

This method updates the internal configuration to use the given tenant in subsequent API calls.

Framework-specific integrations may set context automatically, so calling withContext every time may not be necessary in those environments. see extensions for more information

This ID is typically sourced from:

The result of create()
A specific tenant via get()
A selected tenant from list()

const tenants = await nile.tenants.list();
if (!(tenants instanceof Response)) {
  nile.withContext({ tenantId: tenants[0].id });
}

If not explicitly set, an error will be thrown by the SDK if the tenant Id is missing.

create

Create a new tenant using POST /api/tenants. The current user is automatically linked to the new tenant.

const tenant = await nile.tenants.create('Acme Inc');

const tenant = await nile.tenants.create({ name: 'My Org', id: 'custom-uuid' });

Parameters

name: Name of the tenant (required)
id: Optional. Unique ID to use instead of auto-generating

Returns

If successful, resolves to a Tenant object:

interface Tenant {
  id: string;
  name: string;
}

Returns a Response with 401 or 400 on failure.

get

Fetch a specific tenant or the current tenant using GET /api/tenants/{id}.

const tenant = await nile.tenants.get('0196...');

const n = await nile.withContext({ tenantId: '0196...' });
const tenant = await n.tenants.get();

Parameters

id: Optional. If omitted, uses the current context

Returns

A Tenant object or a raw Response.

update

Update the name of the current tenant via PUT /api/tenants/{id}.

const n = await nile.withContext({ tenantId: '0196...' });
const tenant = await n.tenants.update({ name: 'New Name' });

Parameters

name: New name of the tenant
id: Optional. If omitted, uses context

Returns

Updated Tenant object or a Response.

Only the name is currently updatable.

delete

Mark a tenant as deleted using DELETE /api/tenants/{id}. This is a soft delete.

const res = await nile.tenants.delete('0196...');

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.delete();

Returns

A Response with status 204 on success.

list

List all tenants the current user belongs to via GET /api/tenants/by-user.

const tenants = await nile.tenants.list();

Returns

Array of Tenant objects:

[{ id: '...', name: '...' }];

401 if the user is unauthenticated.

users

List users who are members of a given tenant (or the current one).

const n = await nile.withContext({ tenantId: '0196...' });
const users = await n.tenants.users();

Returns

Array of User objects, or a Response on error.

addMember

Add a user to the current tenant using their user ID.

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.addMember('user-id');

Returns

The added User object or a Response.

removeMember

Remove a user from the tenant.

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.removeMember('user-id');

Returns

A Response.

leaveTenant

Removes the current user from a tenant they belong to.

const n = await nile.WithContext({ tenantId: '0196...' });
await n.tenants.leaveTenant();

Returns

A Response.

invites

Fetch all invites for the current tenant:

const n = await nile.withContext({ tenantId: '0196...' });
const invites = await n.tenants.invites();

Returns

An array of Invite objects.

invite

Invite a new user by email to the current tenant. the callbackUrl is the value that is used to return the user to a page that renders HTML. There is a primary endpoint that is used to exchange the token in the email to join the tenant. Upon a successful exchange, the user will be redirected to the callbackUrl

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.invite('user@example.com');

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.invite({
  email: 'user@example.com',
  callbackUrl: 'https://myapp.com/welcome',
});

Parameters

email: Email of the user to invite
callbackUrl: Optional URL to redirect after acceptance
redirectUrl: Optional URL used as the base in the email

Returns

An Invite object or a Response.

acceptInvite

Accept an invite using an emailed token and email address.

await nile.tenants.acceptInvite({ identifier: 'email', token: '123' });

Returns

A Response indicating success or failure.

deleteInvite

Delete a previously sent invite.

await nile.tenants.deleteInvite('invite-id');

Returns

A Response.

Nile Auth

Frameworks

Setting the Current Tenant

create

Parameters

Returns

get

Parameters

Returns

update

Parameters

Returns

delete

Returns

list

Returns

users

Returns

addMember

Returns

removeMember

Returns

leaveTenant

Returns

invites

Returns

invite

Parameters

Returns

acceptInvite

Returns

deleteInvite

Returns

​Setting the Current Tenant

​create

​Parameters

​Returns

​get

​Parameters

​Returns

​update

​Parameters

​Returns

​delete

​Returns

​list

​Returns

​users

​Returns

​addMember

​Returns

​removeMember

​Returns

​leaveTenant

​Returns

​invites

​Returns

​invite

​Parameters

​Returns

​acceptInvite

​Returns

​deleteInvite

​Returns

Setting the Current Tenant

create

Parameters

Returns

get

Parameters

Returns

update

Parameters

Returns

delete

Returns

list

Returns

users

Returns

addMember

Returns

removeMember

Returns

leaveTenant

Returns

invites

Returns

invite

Parameters

Returns

acceptInvite

Returns

deleteInvite

Returns