WebSocket & GraphQL Authentication ​

Authentication is an important part of establishing your persistent connection with a Directus project.

Authentication Modes ​

There are three authentication modes in Directus.

Changing Authentication Modes ​

Your whole project will use the same, single, authentication mode. You cannot use multiple authentication modes in a single project.

By default, the handshake authentication mode is used. If self-hosting your project, you may change the mode used by setting the WEBSOCKETS_REST_AUTH and WEBSOCKETS_GRAPHQL_AUTH environment variables.

REST Authentication Flow ​

Public Mode ​

You do not need to authenticate if using a public authentication mode, but you are limited to the public role only.

If you want to change your role, follow the flow for the handshake authentication mode.

Handshake Mode ​

Your first message must include authentication details and be sent before the timeout. There are three options:

Access Token

{
	"type": "auth",
	"access_token": "your-access-token"
}

{
	"type": "auth",
	"access_token": "your-access-token"
}

Email and Password

{
	"type": "auth",
	"email": "user@email.com",
	"password": "your-password"
}

{
	"type": "auth",
	"email": "user@email.com",
	"password": "your-password"
}

Refresh Token

{
	"type": "auth",
	"refresh_token": "token"
}

{
	"type": "auth",
	"refresh_token": "token"
}

On successful authentication you’ll receive a confirmation message. This message includes a refresh_token when using email/password and refresh_token credentials.

{
	"type": "auth",
	"status": "ok",
	"refresh_token": "a-token-to-use-later"
}

{
	"type": "auth",
	"status": "ok",
	"refresh_token": "a-token-to-use-later"
}

When the client receives an auth expired error, a new authentication request is expected within the set timeout or the connection will be closed.

Strict Mode ​

When initially opening your connection, add a access_token query parameter to your request.

Once initially authenticated, all 3 authentication are available.

GraphQL Authentication Flow ​

GraphQL puts more responsibility on the client for handling the re-authentication flow and has no supported way for us to implement it without breaking compatibility with existing clients. Because of this, you may only use an access_token for authentication at this time.

When a token expires, the connection will be closed with a Forbidden message, signaling to the client to refresh their access_token and reconnect.

Public Mode ​

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql',
	keepAlive: 30000,
});

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql',
	keepAlive: 30000,
});

Handshake Mode ​

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql',
	keepAlive: 30000,
	connectionParams: async () => {
		return { access_token: 'MY_TOKEN' };
	},
});

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql',
	keepAlive: 30000,
	connectionParams: async () => {
		return { access_token: 'MY_TOKEN' };
	},
});

Strict Mode ​

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql?access_token=your-access-token',
	keepAlive: 30000,
});

import { createClient } from 'graphql-ws';

const client = createClient({
	url: 'ws://your-directus-url/graphql?access_token=your-access-token',
	keepAlive: 30000,
});

Rate Limiter / Messenger ​

WebSockets and GraphQL Subscriptions use the same globally-set configuration for the rate limiter and messenger.