Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/directus/directus/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
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);
});

​
Read Users with Query

Filter, sort, and select specific user fields: 
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,
  })
);

​
Read Single User

Retrieve a specific user by ID: 
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);

​
Read Current User

Retrieve the currently authenticated user’s information: 
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}`);

​
Create Operations

​
Create Single User

Create a new user: 
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}`);

​
Create Multiple 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',
    },
  ])
);

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

​
Update Operations

​
Update Single User

Update a user’s information: 
import { updateUser } from '@directus/sdk';

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

​
Update Current User

Update the currently authenticated user’s profile: 
import { updateMe } from '@directus/sdk';

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

​
Update Multiple Users

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

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

​
Delete Operations

​
Delete Single User

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

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

​
Delete Multiple Users

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

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}`);
});

​
Filter Users by Role

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

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

​
Password Management

​
Request Password Reset

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

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

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

​
Reset Password

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

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

​
User Invitations

​
Invite User

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

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

console.log('Invitation sent');

​
Accept User Invitation

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