Authentication

Since SurrealDB is a database that is designed to be used in a distributed environment, it is important to secure the database and the data that is stored in it. SurrealDB provides a number of methods for authenticating users and securing the database.

User authentication

SurrealDB supports user authentication using a number of methods, including:

.signup()

Signs up to a specific authentication scope.

Method Syntax
async db.signup({`{ namespace, database, [ scope | access ], [...] }`})

Arguments

Arguments		Description
namespaceREQUIRED		The namespace to sign up to
databaseREQUIRED		The database to sign up to
scopeREQUIRED1.x		The scope to sign up to. Also pass any variables used in the scope. Only supported in SurrealDB 1.x
accessREQUIRED>= 2.x		The access to sign up to. Also pass any variables used in the access. Only supported from SurrealDB 2.x onwards

Example usage

const token = await db.signup({
	namespace: 'surrealdb',
	database: 'docs',
	scope: 'user',

	// Also pass any properties required by the scope definition
	email: 'info@surrealdb.com',
	pass: '123456',
});

.signin()

Signs in to a root, namespace, database or scope user.

Method Syntax
async db.signin({`{ ... }`})

Arguments

Properties		Description
usernameREQUIRED FOR ROOT, NAMESPACE & DATABASE		The username of the database user
passwordREQUIRED FOR ROOT, NAMESPACE & DATABASE		The password of the database user
namespaceREQUIRED FOR DATABASE & SCOPE/ACCESS		The namespace to sign in to
databaseREQUIRED FOR SCOPE/ACCESS		The database to sign in to
scope1.x		The scope to sign in to. Also pass any variables used in the scope. Only supported in SurrealDB 1.x
access>= 2.x		The access to sign in to. Also pass any variables used in the access. Only supported from SurrealDB 2.x onwards

Example usage

// Authenticate with a root user
const token = await db.signin({
	username: 'root',
	password: 'surrealdb',
});

// Authenticate with a Namespace user
const token = await db.signin({
	namespace: 'surrealdb',
	username: 'tobie',
	password: 'surrealdb',
});

// Authenticate with a Database user
const token = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	username: 'tobie',
	password: 'surrealdb',
});

// Authenticate with a Scope user
const token = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	scope: 'user',

	// Also pass any properties required by the scope definition
	email: 'info@surrealdb.com',
	pass: '123456',
});

.invalidate()

Invalidates the authentication for the current connection.

Method Syntax
async db.invalidate()

Example usage

await db.invalidate();

.authenticate()

Authenticates the current connection with a JWT token.

Method Syntax
async db.authenticate(token)

Arguments

Arguments		Description
tokenREQUIRED		The JWT authentication token.

Example usage

await db.authenticate('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA');

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.