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 utilizes 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 necessary information for User Authentication or Access Authentication. The required parameters vary depending on the authentication type:

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 }
Scope User	{ sc: string, ns: string, db: string, [param: string]: unknown }

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.disconnect();

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.disconnect();

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.disconnect();

The following example signs in to SurrealDB as a scope user. .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",
  sc: "account",
  // ...parameters
});

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

await db.disconnect();

.signup() instance method

Signs up to SurrealDB as a scope user.

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

Arguments

auth

Contains the necessary information for a scope user.

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",
  sc: "account",
  // ...parameters
});

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

await db.disconnect();

.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.