The Users module is used to manage users. It provides a number of methods for creating, updating, and deleting users.

​
createUser

The nile.api.users.createUser method is used to create a new user.

​
Parameters

  • email: The email of the user to create.
  • password: The password of the user to create.
  • preferredName: Optional. The preferred name of the user to create.
  • newTenant: Optional. Name of a new tenant to create for the user.

​
Returns

When successful, a promise that resolves to a User object.

interface User {
  id: string;
  email: string;
  name?: string | null;
  familyName?: string | null;
  givenName?: string | null;
  picture?: string | null;
  created: string;
  updated?: string;
  emailVerified?: string | null;
  tenants: { id: string }[];
}

When the user already exists, a promise that resolves to a Response object with 404 status code and text body Not Found.

​
Examples

Here are some examples of how to use the nile.api.users.createUser method and the expected responses:

const user = await nile.api.users.createUser({
  email: 'test@example.com',
  password: 'password',
});

if (user instanceof Response) {
    console.log("User creation failed:", { status: user.status, body: await user.text() });
} else {
    console.log("User creation successful");
    console.log(user);
}

// Example response:
// {
//   id: '019609a8-ef6e-7df8-a50e-418a703d3cc1',
//   email: 'test@example.com',
//   name: null,
//   familyName: null,
//   givenName: null,
//  picture: null,
//  created: '2025-04-06T05:53:08.461Z',
//  updated: '2025-04-06T05:53:08.461Z',
//  tenants: []
// }

​
createTenantUser

The nile.api.users.createTenantUser method is used to create a new user in the current tenant.

​
Parameters

  • email: The email of the user to create.
  • password: The password of the user to create.
  • preferredName: Optional. The preferred name of the user to create.
  • newTenant: Optional and unused.

​
Returns

When successful, a promise that resolves to a User object.

interface User {
  id: string;
  email: string;
  name?: string | null;
  familyName?: string | null;
  givenName?: string | null;
  picture?: string | null;
  created: string;
  updated?: string;
  emailVerified?: string | null;
}

If unauthenticated, a promise that resolves to a Response object with 401 status code.

​
Examples

createTenantUser
 const newTenantUser = await nile.api.users.createTenantUser({
  email: 'test@example.com',
  password: 'password',
});

if (newTenantUser instanceof Response) {
    console.log("User creation failed:", { status: newTenantUser.status, body: await newTenantUser.text() });
} else {
    console.log("User creation successful");
    console.log(newTenantUser);
}

// Example response:
// {
//   id: '019616c4-34ac-7f0c-98e5-693fdd00e606',
//   email: 'newtenantuser@me.com',
//   name: null,
//   familyName: null,
//   givenName: null,
//   picture: null,
//   created: '2025-04-08T18:57:59.468Z',
//   updated: '2025-04-08T18:57:59.468Z',
//   emailVerified: null
// }

​
me

The nile.api.users.me method is used to get information about the current user.

​
Returns

If succeeds, a promise that resolves to a User object.

interface User {
  id: string;
  email: string;
  name?: string | null;
  familyName?: string | null;
  givenName?: string | null;
  picture?: string | null;
  created: string;
  updated?: string;
  emailVerified?: string | null;
  tenants: { id: string }[];
}

If unauthenticated, a promise that resolves to a Response object with 401 status code.

​
Examples

me
const user = await nile.api.users.me();
console.log(user);

// Example response:
// Me:  {
//   id: '0195f4de-4721-7712-8261-327ede439e11',
//   email: 'testRunner@thenile.dev',
//   name: 'Test User',
//   familyName: '',
//   givenName: '',
//   picture: '',
//  created: '2025-04-02T04:59:22.784Z',
//  updated: '2025-04-02T04:59:22.784Z',
//  emailVerified: null,
//  tenants: [
//    { id: '019612d6-e550-73ba-9fca-f4868f8e2787' },
//    { id: '019612d7-56e7-7e87-8f30-ad6b05d85645' }
//  ]
// }

​
updateMe

The nile.api.users.updateMe method is used to update the current user.

​
Parameters

User object with one or more of the following properties:

  • name
  • familyName
  • givenName
  • picture (string with url to the picture)
  • emailVerified

Email address, ID, created and updated properties cannot be modified. Tenant membership is updated via the nile.api.users.linkTenant and nile.api.users.unlinkTenant methods. Password reset currently cannot be done via the SDK, refer to the Password Reset documentation for more information.

​
Returns

If successful, a promise that resolves to a User object with the new values.

If unauthenticated, a promise that resolves to a Response object with 401 status code.

​
Examples

update the name of the user
const user = await nile.api.users.updateMe({
  name: 'John Doe',
});

console.log(user);

// Example response:
// {
//   id: '0195f4de-4721-7712-8261-327ede439e11',
//   email: 'testRunner@thenile.dev',
//   name: 'John Doe',
//   familyName: '',
//   givenName: '',
//   picture: '',
//   created: '2025-04-02T04:59:22.784Z',
//   updated: '2025-04-02T04:59:22.784Z',
//   emailVerified: null,
//   tenants: []
// }

​
linkUser

The nile.api.users.linkUser method is used to give an existing user access to a tenant.

​
Parameters

  • id: The ID of the user to link.
  • tenantId: Optional. The ID of the tenant to link the user to. If not provided, the user will be linked to the current tenant.

​
Returns

  • User object if successful. This method succeeds even if the user is already a member of the tenant.
User {
  id: string;
  email: string;
  name?: string | null;
  familyName?: string | null;
  givenName?: string | null;
  picture?: string | null;
  created: string;
  updated?: string;
  emailVerified?: string | null;
}
  • 401 Unauthorized if unauthenticated
  • 404 Not Found if the user does not exist, the tenant does not exist, or the current user does not have permission to access the specified tenant.

​
Examples

const linkedUser = await nile.api.users.linkUser({
      id: '019616d4-5fb0-790b-baa7-b26b7f80c65a',
      tenantId: '019612d7-56e7-7e87-8f30-ad6b05d85645'
    });
console.log("Linked user: ", linkedUser);

// Example response:
// Linked user:  {
//   id: '019616d4-5fb0-790b-baa7-b26b7f80c65a',
//   created: '2025-04-08T19:15:39.055Z',
//   updated: '2025-04-08T19:15:39.055Z',
//   deleted: null,
//   name: null,
//   family_name: null,
//   given_name: null,
//   email: 'delete8@me.com',
//   picture: null,
//   email_verified: null
// }

​
unlinkUser

The nile.api.users.unlinkUser method is used to remove user’s access to a tenant, without deleting the user.

​
Parameters

  • userId: The ID of the user to unlink.
  • tenantId: Optional. The ID of the tenant to unlink the user from. If not provided, the user will be unlinked from the current tenant.

​
Returns

  • 204 No Content if successful
  • 401 Unauthorized if unauthenticated
  • 404 Not Found if the user is not a member of the current tenant, the user does not exist, the tenant does not exist, or the current user does not have permission to access the current tenant.

​
Examples

const response = await nile.api.users.unlinkUser({
      id: '019616d4-5fb0-790b-baa7-b26b7f80c65a',
      tenantId: '019612d7-56e7-7e87-8f30-ad6b05d85645'
    });
console.log("Unlinking user status : ", response.status);
// Expected response:
// Unlinking user status :  204

​
listUsers

The nile.api.users.listUsers method is used to list all users in the current tenant.

​
Returns

  • Array with User objects if successful.
  • 401 Unauthorized if unauthenticated.
  • 400 If current tenant is not set (nile.tenantId is null or undefined).
  • 404 Not Found if the current user does not have permission to access the current tenant.

​
Examples

listUsers
const users = await nile.api.users.listUsers();
console.log("Users: ", users);

// Example response:
// list users:  [
//   {
//     id: '019616d2-a4c7-71e4-957e-c4e4b07698fa',
//     email: 'user5@me.com',
//     name: null,
//     familyName: null,
//     givenName: null,
//     picture: null,
//     emailVerified: null
//   },
//   {
//     id: '019616d4-5fb0-790b-baa7-b26b7f80c65a',
//     email: 'user8@me.com',
//     name: null,
//     familyName: null,
//     givenName: null,
//     picture: null,
//     emailVerified: null
//   }
// ]

​
updateUser

The nile.api.users.updateUser method is used to update a user. A user can only update other users in the same tenant.

​
Parameters

User object with one or more of the following properties:

  • id
  • name
  • familyName
  • givenName
  • picture (string with url to the picture)
  • emailVerified

If id is not provided, the method will use the id from nile.userId.

Email address, ID, created and updated properties cannot be modified. Tenant membership is updated via the nile.api.users.linkTenant and nile.api.users.unlinkTenant methods. Password reset currently cannot be done via the SDK, refer to the Password Reset documentation for more information.

​
Returns

If successful, a promise that resolves to a User object with the new values.

If unauthenticated, a promise that resolves to a Response object with 401 status code. If the current user does not share a tenant with the user being updated, a promise that resolves to a Response object with 404 status code.

​
Examples


const updateResponse = await nile.api.users.updateUser({
    id: '019617c4-6d5d-7b1a-89d1-d6638c8512e3',
    name: 'Different name',
});
console.log("update response: ", updateResponse);

// Example response:
// {
//   id: '019617c4-6d5d-7b1a-89d1-d6638c8512e3',
//   email: 'userb2@me.org',
//   name: 'Different name',
//   familyName: '',
//   givenName: '',
//   picture: '',
//   created: '2025-04-08T23:37:51.196Z',
//   updated: '2025-04-08T23:37:51.196Z'
// }