Skip to main content

Logging in users

A user must be logged in before they can start making actions (uploading, annotating, etc).

There are three ways to login a user. One is with a username & password, one is with an authentication token, and you can also log users in anonymously.

Username and password#

To login a user with a username and password, you can use the loginWithPassword function.

client.loginWithPassword(email, password): Promise<User>

The username and password provided will be passed into your verifyPassword function on the server. If the username and password are valid, the user will be logged in. If they are not, the promise will be rejected with an error.

This function resolves to a User object that you can use to manage documents.

Authentication token#

You can also login a user using an authentication token via the loginWithToken function.

client.loginWithToken(token): Promise<User>

This function will pass the authentication token into your getUserFromToken function on the server. If the token is valid, the user will be logged in, otherwise the promise will be rejected with an error.

If you need to pass multiple tokens, you can stringify an object and send it to the server, and then parse the JSON in your getUserFromToken function.

// Client side
client.loginWithToken(JSON.stringify({ token1: 'abc', token2: 'def' }))
// Server side
new CollabServer({
getUserFromToken: (token) => {
token = JSON.parse(token);
}
})

This function resolves to a User object that you can use to manage documents.

Anonymously#

To log in a user anonymously, see this guide.

Logging out users#

A user can be logged out with the User.logout API.

const user = await client.loginWithToken('token')
await user.logout()

Troubleshooting#

If you are experiencing issues setting up user authentication, we recommend enabling authentication specific debug logs on both the server and client:

// Server side
const server = new CollabServer({
logLevel: CollabServer.LogLevels.DEBUG,
filterLogsByTag: CollabServer.LogTags.AUTH,
})
// Client side
const client = new CollabClient({
logLevel: CollabClient.LogLevels.DEBUG,
filterLogsByTag: CollabClient.LogTags.AUTH
})

Once enabled, logs related to authentication can be seen in both your server and client consoles. These logs can provide insight into what might be going wrong.

Next steps#