Authentication

SurrealDB supports multiple levels of authentication, from system users to fine-grained record-level access. The JavaScript SDK provides methods for signing up and signing in users, managing tokens, and automatically restoring sessions on reconnect.

API References

Signing in users

The .signin() method authenticates an existing user. SurrealDB supports multiple authentication levels, and the properties you provide determine which level is used.

const tokens = await db.signin({
	username: 'root',
	password: 'surrealdb',
});

const tokens = await db.signin({
	namespace: 'surrealdb',
	username: 'tobie',
	password: 'surrealdb',
});

const tokens = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	username: 'tobie',
	password: 'surrealdb',
});

const tokens = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	access: 'account',
	variables: {
		email: 'info@surrealdb.com',
		pass: '123456',
	},
});

On success, the method returns a Tokens object containing the access token and an optional refresh token. The session is automatically authenticated after signing in.

Signing up users

The .signup() method creates a new record user through a defined record access method. You must specify the namespace, database, and access method, along with any variables expected by the access definition.

const tokens = await db.signup({
    namespace: 'surrealdb',
    database: 'docs',
    access: 'account',
    variables: {
        email: 'info@surrealdb.com',
        pass: '123456',
    },
});

Much like the .signin() method, the .signup() method returns a Tokens object containing the access token and an optional refresh token. The session is automatically authenticated after signing up.

Authenticating with an existing token

If you already have an access token (for example, stored from a previous session), you can authenticate using the .authenticate() method instead of signing in again. This is useful for restoring a user’s session without re-entering credentials.

await db.authenticate(accessToken);

When you have a refresh token available, you can pass both tokens as an object. The SDK will exchange the refresh token for a new token pair.

const newTokens = await db.authenticate({
    access: oldAccessToken,
    refresh: refreshToken,
});

Providing credentials on connect

Rather than calling .signin() separately, you can pass authentication credentials directly to the .connect() method using the authentication option. This is the preferred approach for system users because it allows the SDK to automatically re-authenticate when the connection drops and reconnects.

await db.connect('ws://127.0.0.1:8000', {
    namespace: 'surrealdb',
    database: 'docs',
    authentication: {
        username: 'root',
        password: 'surrealdb',
    },
});

The authentication option also accepts an async function, allowing you to retrieve credentials dynamically.

await db.connect('ws://127.0.0.1:8000', {
    namespace: 'surrealdb',
    database: 'docs',
    authentication: async () => ({
        username: await getUsername(),
        password: await getPassword(),
    }),
});

See the full list of connection options in the ConnectOptions type reference.

Note

When you call .signup() or .signin() manually, the authentication property passed to .connect() is no longer used for automatic re-authentication. You become responsible for handling token expiry by listening to the auth event.

Listening to authentication events

The SDK emits an auth event whenever the authentication state changes, including on sign in, sign up, token refresh, or invalidation. You can subscribe to this event using the .subscribe() method.

db.subscribe('auth', (tokens) => {
    if (tokens) {
        console.log('Authenticated:', tokens.access);
    } else {
        console.log('Signed out');
    }
});

This is particularly useful for record access, where you can subscribe to the auth event to automatically update UI or other components when the authentication state changes.

Accessing authentication state

The SDK exposes the current authentication tokens through the .accessToken property on any Surreal or SurrealSession instance. This is useful for checking whether the current session is authenticated or for forwarding tokens to other services.

if (db.accessToken) {
    console.log('Session is authenticated');
}

Signing out

The .invalidate() method signs the current user out by clearing the session’s authentication state. After calling this method, any subsequent queries will run without authentication.

await db.invalidate();

Using isolated sessions

You can create multiple isolated sessions within a single connection, each with their own namespace, database, variables, and authentication state. This is useful when different parts of your application need to operate under different credentials or contexts.

const session = await db.newSession();

await session.signin({
    namespace: 'surrealdb',
    database: 'docs',
    access: 'account',
    variables: {
        email: 'info@surrealdb.com',
        pass: '123456',
    },
});

const users = await session.select('users');

await session.closeSession();

Learn more

• SurrealSession API reference for authentication method signatures
• Authentication types reference for all credential type definitions
• Authentication in SurrealDB for how authentication works at the database level
• Security best practices for securing your application
• DEFINE ACCESS for defining access methods with SurrealQL
• DEFINE USER for creating system users
• Connecting to SurrealDB for connection setup and reconnection behavior
• Multiple sessions for isolated session management