Authentication

There are three authentication modes in Directus Realtime.

handshake is the default authentication mode.

Changing Authentication Modes

You can only use one authentication mode at a time in a single project.

If self-hosting your project, you can set authentication modes by setting the WEBSOCKETS_REST_AUTH, WEBSOCKETS_GRAPHQL_AUTH and WEBSOCKETS_LOGS_AUTH environment variables to one of these modes. By default, they are set to the handshake mode.

Public Mode

Websockets

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

In order to change roles, follow the flow for the handshake authentication mode.

GraphQL

import { createClient } from "graphql-ws";

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

Handshake Mode

Websockets

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"
}

Email and Password

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

Refresh 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"
}

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

GraphQL

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

Websockets

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

Once initially authenticated, all 3 authentication are available.

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.

GraphQL

import { createClient } from "graphql-ws";

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

Authentication with GraphQL

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.