SDK Users Operations

Overview

The Directus SDK provides comprehensive user management capabilities, including reading user data, updating user profiles, and accessing the current authenticated user’s information.

Read Operations

Read All Users

Retrieve a list of all users:

TypeScript
JavaScript

import { createDirectus, rest, readUsers } from '@directus/sdk';

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest());

const users = await client.request(
  readUsers()
);

users.forEach(user => {
  console.log(user.email);
  console.log(user.first_name);
  console.log(user.last_name);
});

import { createDirectus, rest, readUsers } from '@directus/sdk';

const client = createDirectus('https://your-directus-url.com')
  .with(rest());

const users = await client.request(
  readUsers()
);

Read Users with Query

Filter, sort, and select specific user fields:

TypeScript
JavaScript

import { readUsers } from '@directus/sdk';

const activeUsers = await client.request(
  readUsers({
    filter: {
      status: { _eq: 'active' },
    },
    fields: ['id', 'email', 'first_name', 'last_name', 'role.name'],
    sort: ['first_name', 'last_name'],
    limit: 50,
  })
);

import { readUsers } from '@directus/sdk';

const activeUsers = await client.request(
  readUsers({
    filter: {
      status: { _eq: 'active' },
    },
    fields: ['id', 'email', 'first_name', 'last_name'],
  })
);

Read Single User

Retrieve a specific user by ID:

TypeScript
JavaScript

import { readUser } from '@directus/sdk';

const user = await client.request(
  readUser('user-id', {
    fields: ['*', 'role.*', 'avatar.*'],
  })
);

console.log(user.email);
console.log(user.role?.name);

import { readUser } from '@directus/sdk';

const user = await client.request(
  readUser('user-id')
);

Read Current User

Retrieve the currently authenticated user’s information:

TypeScript
JavaScript

import { readMe } from '@directus/sdk';

const currentUser = await client.request(
  readMe({
    fields: ['*', 'role.*', 'avatar.*'],
  })
);

console.log(`Logged in as: ${currentUser.email}`);
console.log(`Role: ${currentUser.role?.name}`);

import { readMe } from '@directus/sdk';

const currentUser = await client.request(
  readMe()
);

console.log(`Logged in as: ${currentUser.email}`);

Create Operations

Create Single User

Create a new user:

TypeScript
JavaScript

import { createUser } from '@directus/sdk';

const newUser = await client.request(
  createUser({
    email: 'newuser@example.com',
    password: 'secure-password',
    first_name: 'John',
    last_name: 'Doe',
    role: 'role-id',
    status: 'active',
  })
);

console.log(`Created user: ${newUser.id}`);

import { createUser } from '@directus/sdk';

const newUser = await client.request(
  createUser({
    email: 'newuser@example.com',
    password: 'secure-password',
    role: 'role-id',
  })
);

Create Multiple Users

TypeScript
JavaScript

import { createUsers } from '@directus/sdk';

const newUsers = await client.request(
  createUsers([
    {
      email: 'user1@example.com',
      password: 'password1',
      role: 'role-id',
    },
    {
      email: 'user2@example.com',
      password: 'password2',
      role: 'role-id',
    },
  ])
);

console.log(`Created ${newUsers.length} users`);

import { createUsers } from '@directus/sdk';

const newUsers = await client.request(
  createUsers([
    { email: 'user1@example.com', password: 'password1', role: 'role-id' },
    { email: 'user2@example.com', password: 'password2', role: 'role-id' },
  ])
);

Update Operations

Update Single User

Update a user’s information:

TypeScript
JavaScript

import { updateUser } from '@directus/sdk';

const updatedUser = await client.request(
  updateUser('user-id', {
    first_name: 'Jane',
    last_name: 'Smith',
    title: 'Senior Developer',
  })
);

import { updateUser } from '@directus/sdk';

const updatedUser = await client.request(
  updateUser('user-id', {
    first_name: 'Jane',
  })
);

Update Current User

Update the currently authenticated user’s profile:

TypeScript
JavaScript

import { updateMe } from '@directus/sdk';

const updatedProfile = await client.request(
  updateMe({
    first_name: 'Updated Name',
    description: 'Updated bio',
    avatar: 'file-id',
  })
);

import { updateMe } from '@directus/sdk';

const updatedProfile = await client.request(
  updateMe({
    first_name: 'Updated Name',
  })
);

Update Multiple Users

TypeScript
JavaScript

import { updateUsers } from '@directus/sdk';

const updatedUsers = await client.request(
  updateUsers(['user-id-1', 'user-id-2'], {
    status: 'suspended',
  })
);

import { updateUsers } from '@directus/sdk';

const updatedUsers = await client.request(
  updateUsers(['user-id-1', 'user-id-2'], {
    status: 'suspended',
  })
);

Delete Operations

Delete Single User

TypeScript
JavaScript

import { deleteUser } from '@directus/sdk';

await client.request(
  deleteUser('user-id')
);

import { deleteUser } from '@directus/sdk';

await client.request(deleteUser('user-id'));

Delete Multiple Users

TypeScript
JavaScript

import { deleteUsers } from '@directus/sdk';

await client.request(
  deleteUsers(['user-id-1', 'user-id-2'])
);

import { deleteUsers } from '@directus/sdk';

await client.request(
  deleteUsers(['user-id-1', 'user-id-2'])
);

User Properties

The DirectusUser object contains these key properties:

interface DirectusUser {
  id: string;
  first_name: string | null;
  last_name: string | null;
  email: string;
  password?: string; // Only for create/update
  location: string | null;
  title: string | null;
  description: string | null;
  tags: string[] | null;
  avatar: string | DirectusFile | null;
  language: string | null;
  tfa_secret: string | null;
  status: 'active' | 'invited' | 'draft' | 'suspended' | 'archived';
  role: string | DirectusRole | null;
  token: string | null;
  last_access: string | null;
  last_page: string | null;
  provider: string;
  external_identifier: string | null;
  auth_data: Record<string, any> | null;
  email_notifications: boolean;
  appearance: string | null;
  theme_dark: string | null;
  theme_light: string | null;
  theme_light_overrides: Record<string, any> | null;
  theme_dark_overrides: Record<string, any> | null;
}

Working with Roles

Read Users with Role Information

TypeScript
JavaScript

import { readUsers } from '@directus/sdk';

const usersWithRoles = await client.request(
  readUsers({
    fields: ['id', 'email', 'role.id', 'role.name', 'role.admin_access'],
  })
);

usersWithRoles.forEach(user => {
  console.log(`${user.email}: ${user.role?.name}`);
});

import { readUsers } from '@directus/sdk';

const usersWithRoles = await client.request(
  readUsers({
    fields: ['id', 'email', 'role.name'],
  })
);

Filter Users by Role

TypeScript
JavaScript

import { readUsers } from '@directus/sdk';

const admins = await client.request(
  readUsers({
    filter: {
      'role.admin_access': { _eq: true },
    },
    fields: ['*', 'role.*'],
  })
);

import { readUsers } from '@directus/sdk';

const admins = await client.request(
  readUsers({
    filter: {
      'role.admin_access': { _eq: true },
    },
  })
);

Password Management

Request Password Reset

TypeScript
JavaScript

import { passwordRequest } from '@directus/sdk';

await client.request(
  passwordRequest('user@example.com')
);

console.log('Password reset email sent');

import { passwordRequest } from '@directus/sdk';

await client.request(
  passwordRequest('user@example.com')
);

Reset Password

TypeScript
JavaScript

import { passwordReset } from '@directus/sdk';

await client.request(
  passwordReset('reset-token', 'new-password')
);

import { passwordReset } from '@directus/sdk';

await client.request(
  passwordReset('reset-token', 'new-password')
);

User Invitations

Invite User

TypeScript
JavaScript

import { inviteUser } from '@directus/sdk';

const invitation = await client.request(
  inviteUser('newuser@example.com', 'role-id')
);

console.log('Invitation sent');

import { inviteUser } from '@directus/sdk';

await client.request(
  inviteUser('newuser@example.com', 'role-id')
);

Accept User Invitation

TypeScript
JavaScript

import { acceptUserInvite } from '@directus/sdk';

await client.request(
  acceptUserInvite('invitation-token', 'secure-password')
);

import { acceptUserInvite } from '@directus/sdk';

await client.request(
  acceptUserInvite('invitation-token', 'secure-password')
);

Type Signatures

// Read operations
function readUsers<Schema, TQuery>(
  query?: TQuery
): RestCommand<DirectusUser<Schema>[], Schema>;

function readUser<Schema, TQuery>(
  key: string,
  query?: TQuery
): RestCommand<DirectusUser<Schema>, Schema>;

function readMe<Schema, TQuery>(
  query?: TQuery
): RestCommand<DirectusUser<Schema>, Schema>;

// Create operations
function createUser<Schema, TQuery>(
  user: Partial<DirectusUser<Schema>>,
  query?: TQuery
): RestCommand<DirectusUser<Schema>, Schema>;

// Update operations
function updateUser<Schema, TQuery>(
  key: string,
  data: Partial<DirectusUser<Schema>>,
  query?: TQuery
): RestCommand<DirectusUser<Schema>, Schema>;

function updateMe<Schema, TQuery>(
  data: Partial<DirectusUser<Schema>>,
  query?: TQuery
): RestCommand<DirectusUser<Schema>, Schema>;

// Delete operations
function deleteUser<Schema>(
  key: string
): RestCommand<void, Schema>;

Next Steps

Authentication

Learn about user authentication

Roles

Manage user roles and permissions

Files

Manage user avatars and files

Activity

Track user activity and actions

REST API

GraphQL

SDK

WebSocket

SDK Users Operations

Overview

Read Operations

Read All Users

Read Users with Query

Read Single User

Read Current User

Create Operations

Create Single User

Create Multiple Users

Update Operations

Update Single User

Update Current User

Update Multiple Users

Delete Operations

Delete Single User

Delete Multiple Users

User Properties

Working with Roles

Read Users with Role Information

Filter Users by Role

Password Management

Request Password Reset

Reset Password

User Invitations

Invite User

Accept User Invitation

Type Signatures

Next Steps

Authentication

Roles

Files

Activity

​Overview

​Read Operations

​Read All Users

​Read Users with Query

​Read Single User

​Read Current User

​Create Operations

​Create Single User

​Create Multiple Users

​Update Operations

​Update Single User

​Update Current User

​Update Multiple Users

​Delete Operations

​Delete Single User

​Delete Multiple Users

​User Properties

​Working with Roles

​Read Users with Role Information

​Filter Users by Role

​Password Management

​Request Password Reset

​Reset Password

​User Invitations

​Invite User

​Accept User Invitation

​Type Signatures

​Next Steps

Authentication

Roles

Files

Activity

Overview

Read Operations

Read All Users

Read Users with Query

Read Single User

Read Current User

Create Operations

Create Single User

Create Multiple Users

Update Operations

Update Single User

Update Current User

Update Multiple Users

Delete Operations

Delete Single User

Delete Multiple Users

User Properties

Working with Roles

Read Users with Role Information

Filter Users by Role

Password Management

Request Password Reset

Reset Password

User Invitations

Invite User

Accept User Invitation

Type Signatures

Next Steps