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

In your SurrealDB database, you can create authentication login using the DEFINE ACCESS statement which supports JWT and Record Access methods.

The access method used will inform the input for access in the .signup() and .signin() methods.

Important
If you are not on Version v2.0.4 of SurrealDB, you will use the scope property instead of access.

Method	Description
`db.signup()`	Connects to a local or remote database endpoint
`db.signin()`	Signs in to a root, namespace, database or scope user
`db.invalidate()`	Invalidates the current session
`db.authenticate()`	Authenticates a user with a token

Defining access in your application

The JavaScript SDK has a .query() method which allows you to write secure SurrealQL statements from within your application. Using this method, you can define access for your users and securely manage authentication. See the code example below:

V2.x
V1.x

...
// Assign the variable on the connection
const authentication = await db.query(
" DEFINE ACCESS account ON DATABASE TYPE RECORD
	SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
	SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
	DURATION FOR TOKEN 15m, FOR SESSION 12h "
;
);
...

...
// Assign the variable on the connection
const authentication = await db.query(
" DEFINE SCOPE user SESSION 24h
	SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
	SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
; "
);
...

User authentication

After you have defined your authentication login, you can use the following methods to authenticate users:

`.signup()`

Signs up to a specific authentication scope / access method.

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

Arguments		Description
`namespace` required		The namespace to sign up to
`database` required		The database to sign up to
`access` required		The access to sign up to. Also pass any variables used in the access under the `variables` key. Only supported from SurrealDB 2.x onwards

Arguments		Description
`namespace` required		The namespace to sign up to
`database` required		The database to sign up to
`scope` required		The scope to sign up to. Also pass any variables used in the scope. Only supported in SurrealDB 1.x

Example usage

V2.x
V1.x

// With Record Access
const token = await db.signup({
	namespace: 'surrealdb',
	database: 'docs',
	access: 'account',

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

// With Scopes
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

V2.x
V1.x

Properties		Description
`username` REQUIRED FOR ROOT, NAMESPACE & DATABASE		The username of the database user
`password` REQUIRED FOR ROOT, NAMESPACE & DATABASE		The password of the database user
`namespace` REQUIRED FOR DATABASE & ACCESS		The namespace to sign in to
`database` REQUIRED FOR ACCESS		The database to sign in to
`access`		The access to sign in to. Also pass any variables used in the access under the `variables` key. Only supported from SurrealDB 2.x onwards

Properties		Description
`username` REQUIRED FOR ROOT, NAMESPACE & DATABASE		The username of the database user
`password` REQUIRED FOR ROOT, NAMESPACE & DATABASE		The password of the database user
`namespace` REQUIRED FOR DATABASE & SCOPE		The namespace to sign in to
`database` REQUIRED FOR SCOPE		The database to sign in to
`scope`		The scope to sign in to. Also pass any variables used in the scope. Only supported in SurrealDB 1.x

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 Record Access
const token = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	access: 'account',

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

// Authenticate with Scopes
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
`token` required		The JWT authentication token.

Example usage

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

Edit this page on GitHub

Create a new connection Set parameters

JavaScript SDK

Handle authentication

Defining access in your application

User authentication

.signup()

Arguments

Example usage

.signin()

Arguments

Example usage

.invalidate()

Example usage

.authenticate()

Arguments

Example usage

On this page

`.signup()`

`.signin()`

`.invalidate()`

`.authenticate()`