Authentication

Etebase automatically takes care of the encryption for you, securely deriving an encryption key from the user password. It then also creates an asymmetric keypair to login so the password never leaves the user's device.

important

Please note that all of the operations in this page are slow and may take a few seconds to complete depending on your device. This is because Etebase purposefully uses a slow function (Argon2id) to derive a secure encryption key from the user password.

Luckily they can be avoided almost entirely for most use-cases. Please take a look at session save and restore for more information.

Signup

Sign up is just one easy call which returns an instance of the main etebase class.

When using a private server, make sure that either sign up is enabled, or that you have created a user beforehand using the Django Admin panel.

// serverUrl can be obtained from the dashboard (or omitted for default)
const etebase = await Etebase.Account.signup({
username: "username",
email: "email"
}, "password", serverUrl);

Login

Login is also just one easy call which returns an instance of the main etebase class.

// serverUrl can be obtained from the dashboard (or omitted for default)
const etebase = await Etebase.Account.login("username", "password", serverUrl);

Change password

Unlike signup and login, changing password requires an already set up etebase object.

await etebase.changePassword("new password");

Logout

await etebase.logout();

Session save and restore

Most apps can't, or don't want the user to enter their passwords every time they are opened, that's why Etebase supports saving and restoring sessions.

Saving and restoring a session is as simple as:

const etebase = await Etebase.Account.login("username", "password", serverUrl);
const savedSession = await etebase.save();
// Later on...
const etebase = await Etebase.Account.restore(savedSession);

Encrypting the stored session

While the above works, it's advised to encrypt the stored session with a randomly generated key that is stored securely (e.g. in the operating system's key store), or securely derived from a user storage password.

const etebase = await Etebase.Account.login("username", "password");
// Save the key somewhere safe (e.g. the OS's key store)
const encryptionKey = Etebase.randomBytes(32);
const savedSession = await etebase.save(encryptionKey);
// Later on...
const etebase = await Etebase.Account.restore(savedSession, encryptionKey);

Email as username

In some cases you don't want a separate username, and would instead like users to be able to login using just their email address. Etebase supports this out of the box, just pass the email instead of the username in the login and anywhere else where Etebase accepts a username.

Etebase however still needs a unique username passed to it during signup, though it can just be randomly generated. So for example, you can use the Etebase utils to generate a username like shown in this psuedo-code:

username = toBase64(randomBytes(24));

Using custom servers

Checking custom server URLs

The login and signup operations above automatically check whether the URL passed is pointing to a valid Etebase server. However, some applications need to know if the URL is pointing to a valid server before asking for credentials. This function does exactly that.

const isEtebase = await Etebase.Account.isEtebaseServer("https://example.com");

Forcing server URL for local development

When saving etebase instances with cacheSave the server URL is also being saved. This is not an issue in production as the URL of the server is unlikely to change, however, when developing against a local server it's often useful to force the server URL without having to login again.

const etebase = await Etebase.Account.restore(savedSession);
etebase.serverUrl = "http://new-development-server";
Edit this page