SDK Authentication

Authenticate with Directus using the SDK

Overview

The Directus SDK provides multiple authentication methods to suit different use cases. You can use full authentication with login/logout/refresh capabilities, or use a static token for server-side applications.

Authentication Methods

Static Token

Use a static access token for server-side applications or when you already have a valid token.

TypeScript

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

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

// The token is automatically included in all requests
const items = await client.request(readItems('articles'));

JavaScript

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

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

const items = await client.request(readItems('articles'));

Full Authentication

Use the authentication() composable for full login/logout capabilities with automatic token refresh.

Authentication Modes

• cookie - Uses HTTP-only cookies (default, recommended for web apps)
• json - Returns tokens in JSON response body (for mobile/desktop apps)

Cookie Mode (Default)

TypeScript

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

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

// Login with email and password
await client.login({
  email: '[e-mail]',
  password: 'password',
});

// Make authenticated requests
const items = await client.request(readItems('articles'));

// Logout
await client.logout();

JavaScript

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

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

await client.login({
  email: '[e-mail]',
  password: 'password',
});

const items = await client.request(readItems('articles'));

await client.logout();

JSON Mode

TypeScript

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

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

// Login returns access and refresh tokens
const authData = await client.login({
  email: '[e-mail]',
  password: 'password',
});

console.log(authData.access_token);
console.log(authData.refresh_token);
console.log(authData.expires); // Token lifetime in milliseconds

JavaScript

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

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

const authData = await client.login({
  email: '[e-mail]',
  password: 'password',
});

console.log(authData.access_token);

LDAP Authentication

For LDAP authentication, provide the provider option:

TypeScript

await client.login(
  {
    identifier: 'username',
    password: 'password',
  },
  {
    provider: 'ldap',
  }
);

JavaScript

await client.login(
  {
    identifier: 'username',
    password: 'password',
  },
  {
    provider: 'ldap',
  }
);

Two-Factor Authentication (OTP)

If the user has 2FA enabled, provide the one-time password:

TypeScript

await client.login(
  {
    email: '[e-mail]',
    password: 'password',
  },
  {
    otp: '123456',
  }
);

JavaScript

await client.login(
  {
    email: '[e-mail]',
    password: 'password',
  },
  {
    otp: '123456',
  }
);

Token Management

Get Current Token

const token = await client.getToken();
console.log(token);

Set Token Manually

await client.setToken('your-access-token');

Automatic Token Refresh

The SDK automatically refreshes tokens before they expire when using authentication() mode.

Configuration

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest())
  .with(authentication('json', {
    autoRefresh: true, // Default: true
    msRefreshBeforeExpires: 30000, // Refresh 30s before expiry (default)
  }));

Manual Refresh

const authData = await client.refresh();
console.log(authData.access_token);

Stop Auto-Refresh

client.stopRefreshing();

Custom Storage

By default, authentication data is stored in memory. You can provide custom storage (e.g., localStorage, AsyncStorage):

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

const customStorage = {
  async get() {
    const data = localStorage.getItem('directus-auth');
    return data ? JSON.parse(data) : null;
  },
  async set(data: any) {
    localStorage.setItem('directus-auth', JSON.stringify(data));
  },
};

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest())
  .with(authentication('json', { storage: customStorage }));

CORS Credentials

For cross-origin requests with cookies:

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest({ credentials: 'include' }))
  .with(authentication('cookie', { credentials: 'include' }));

Authentication Type Signatures

// Login payload types
interface LocalLoginPayload {
  email: string;
  password: string;
}

interface LDAPLoginPayload {
  identifier: string;
  password: string;
}

// Login options
interface LoginOptions {
  provider?: string; // e.g., 'ldap'
  otp?: string; // Two-factor code
  mode?: 'cookie' | 'json';
}

// Authentication data response
interface AuthenticationData {
  access_token: string | null;
  refresh_token: string | null;
  expires: number | null;
  expires_at: number | null;
}

Next Steps

Items Operations

Perform CRUD operations on collection items

Users

Manage users and retrieve current user info

Files

Upload and manage files

Real-time

Subscribe to real-time updates