Authentication

There are two authentication methods available. The first uses a username and password, requiring a username and password defined using the DEFINE USER statement. The second uses custom authentication defined with the DEFINE ACCESS statement. We will refer to the former as “User Authentication” and the latter as “Access Authentication.”

.signin() instance method

Signs in to SurrealDB using User Authentication or Access Authentication.

signin(auth: Auth, options?: ClientRpcOptions): Promise<Jwt>;

Arguments

auth

Contains the information required for User Authentication or Access Authentication. The necessary parameters for each authentication type are as follows:

Authentication Type	Parameters
Root User	{ user: string, pass: string }
Namespace User	{ user: string, pass: string, ns: string }
Database User	{ user: string, pass: string, ns: string, db: string }
Access	{ ac: string, ns: string, db: string, [param: string]: unknown }

Access Authentication typically requires additional parameters based on the defined access (ac).

options

Options for the RPC request.

Return Value

Returns a Promise object that resolves to a Jwt.

Examples

The following example signs in to SurrealDB as the root user:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const jwt = await db.signin({
  user: "root",
  pass: "passw0rd",
});

console.log(jwt.issuedAt);  // e.g. 1722749786
console.log(jwt.expiresAt); // e.g. 1722753386
console.log(jwt.namespace); // undefined
console.log(jwt.database);  // undefined
console.log(jwt.access);    // undefined
console.log(jwt.user);      // 'root'

console.log(jwt.raw);             // 'eyJ0eXAiOiJKV1QiLCJhb ... '
console.log(JSON.stringify(jwt)); // '"[REDACTED]"'

await db.close();

The following example signs in to SurrealDB as a namespace user:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const jwt = await db.signin({
  ns: "my_namespace",
  user: "ns_user",
  pass: "passw0rd",
});

console.log(jwt.namespace); // 'my_namespace'
console.log(jwt.database);  // undefined
console.log(jwt.access);    // undefined
console.log(jwt.user);      // 'ns_user'

await db.close();

The following example signs in to SurrealDB as a database user:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const jwt = await db.signin({
  ns: "my_namespace",
  db: "my_database",
  user: "db_user",
  pass: "passw0rd",
});

console.log(jwt.namespace); // 'my_namespace'
console.log(jwt.database);  // 'my_database'
console.log(jwt.access);    // undefined
console.log(jwt.user);      // 'db_user'

await db.close();

The following example signs in to SurrealDB using record access. .user will be set to the record ID:

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const jwt = await db.signin({
  ns: "my_namespace",
  db: "my_database",
  ac: "account",
  // ...parmeters
});

console.log(jwt.namespace); // 'my_namespace'
console.log(jwt.database);  // 'my_database'
console.log(jwt.access);    // 'account'
console.log(jwt.user);      // e.g. 'user:⟨tai-kun⟩'

await db.close();

.signup() instance method

Signs up to SurrealDB using Access Authentication.

signup(auth: RecordAccessAuth, options?: ClientRpcOptions): Promise<Jwt>;

Arguments

auth

Contains the information required for Access Authentication.

options

Options for the RPC request.

Return Value

Returns a Promise object that resolves to a Jwt.

Examples

import { Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
await db.connect("ws://localhost:8000");

const jwt = await db.signup({
  ns: "my_namespace",
  db: "my_database",
  ac: "account",
  // ...parmeters
});

console.log(jwt.namespace); // 'my_namespace'
console.log(jwt.database);  // 'my_database'
console.log(jwt.access);    // 'account'
console.log(jwt.user);      // e.g. 'user:⟨tai-kun⟩'

await db.close();

.authenticate() instance method

Authenticates the current connection using a JWT.

authenticate(token: string | Jwt, options?: ClientRpcOptions): Promise<void>

Arguments

token

The JWT to authenticate with.

options

Options for the RPC request.

Return Value

Returns a Promise object that resolves to undefined.

.invalidate() instance method

Invalidates the authentication of the current connection.

invalidate(options?: ClientRpcOptions): Promise<void>

Arguments

options

Options for the RPC request.

Return Value

Returns a Promise object that resolves to undefined.