Tenants

Managing tenants for the current user

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()

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

createTenant by name

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

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

getTenant by ID

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

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.

delete by ID

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

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

invite

const n = await nile.withContext({ tenantId: '0196...' });
await n.tenants.invite('[e-mail]');

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.