SimpleJWT Documentation

Overview

SimpleJWT is an API for user management as well as a simple data store for each of your end-users. We are the easiest authentication provider available. To get started, you only need to follow these steps.

1. Add SimpleJWT to your dependencies: npm install sjwt
2. Import what you need: import {register} from 'sjwt';
3. register({email, password, projectId});

The Shape of Errors

Every error you get from SimpleJWT will always have the following shape:

{
    "code": "<an error code>",
    "message": "<a message that can be displayed to your end-user explaining what happened>",
    "errors": [{
        "code": "<an error code>",
        "message": "<a message that can be displayed to your end-user explaining what happened>",
        "value": "<if applicable, the value that caused the error>",
        "param": "<if applicable, the name of the parameter that errored>",
        "location": "<if applicable, where that parameter was>",
    }, ...],
    "context": {<if applicable, additional information>},
}

The top level code key is always the same as errors[0].code. It is always a string, and is always uppercase. You probably should not display this to your end-users, but you can if you want to.

The top level message key is always the same as errors[0].message. It is always a string, always has the first letter capitalized, and never ends with punctuation. This is intended to be displayed to your end-users.

The top level errors key contains an array of all errors that happened. It always has a length of at least one. All errors are guaranteed to have a code and a message that follow the same rules as above.

The top level context key contains any additional information that could potentially help resolve the error given. Generally this is an empty object and can be ignored, but a couple endpoints utilize it.

register()

import {register} from 'sjwt';
register({
    email: 'example@example.com',
    password: 'password',
    projectId: 'YOUR PROJECT ID',
});

Register is used to add end-users to a project with an email address and password. The email must be a valid email according to validator.js and the password must be at least 8 characters long. There are no other restrictions. If the Project allows users to login without verification they will immediately get a token upon registration. Otherwise, they'll get a message with verification details.

Parameters

Response

If your project allows users to register and does not require verification, you will get a response similar to this:

{
    "token": "<a new bearer token>",
    "user": {
        "id": "<the end-user's id>",
        "email": "<the end-user's email address>",
        "publicData": {},
        "privateData": {},
        "createdAt": "2023-08-02T14:32:40.311Z",
        "updatedAt": "2023-08-02T14:32:40.311Z",
        "lastLogin": null,
        "verificationKey": "<the end-user's verification key>",
        "verified": false,
        "suspended": false,
        "project": {
            "id": "<your project's id>",
            "name": "<your project's name>",
            "canRegister": true,
            "requireVerification": false
        }
    }
}

Error Codes

Most of the errors you can get are related to the input your end-user submits. However, a couple can be affected by settings you've configured for the project itself. NEEDS_VALIDATION can only appears if you've required validation in the project while PROJECT_REGISTRATION_DISABLED only appears if you've disabled registration.

login()

import {login} from 'sjwt';
login({
    email: 'example@example.com',
    password: 'password',
    projectId: 'YOUR PROJECT ID',
});

Login is used to authenticate end-users to a project with an email and a password. The user must have already registered with the given project.

Parameters

Response

{
    "token": "<a new bearer token>",
    "user": {
        "id": "<the end-user's id>",
        "email": "<the end-user's email address>",
        "publicData": {},
        "privateData": {},
        "createdAt": "2023-08-02T12:05:56.559Z",
        "updatedAt": "2024-01-13T22:36:58.926Z",
        "lastLogin": "2024-01-13T22:36:58.926Z",
        "verificationKey": "<the end-user's verification key>",
        "verified": false,
        "suspended": false,
        "project": {
            "id": "<your project's id>",
            "name": "<your project's name>",
            "canRegister": true,
            "requireVerification": false
        }
    }
}

logout()

import {logout} from 'sjwt';
logout();

Logout will invalidate all current tokens.

Parameters

none

Response

{
    "success": true
}

getAuthenticatedUser()

import {getAuthenticatedUser} from 'sjwt';
getAuthenticatedUser({
    forceServer: false,
    projectId: 'YOUR PROJECT ID',
});

getAuthenticatedUser() returns the user object of the currently authenticated user or it returns null. If forceServer is set to true, it will send a request to the SJWT servers to validate the current token. Otherwise, it will rely on the user object currently stored in memory, which is managed by the library. If there is no user object locally stored, it will automatically fetch from the server regardless.

In general, you should set forceServer to true whenever you are resuming a session with a token that you retrieved from memory. So any page refreshes, or if the app is re-opened, or even just if the user has been inactive for a few minutes.

Parameters

sjwt.configure()

import {sjwt} from 'sjwt';
sjwt.configure({
    projectId: 'YOUR PROJECT ID',
    saveToken: () => {},
    loadToken: () => {},
    removeToken: () => {},
    version: 'v1',
    host: 'https://api.simplejwt.com',
});

It is useful to configure the SJWT library in two cases. First if you want to call other functions without providing a project ID. Second is if your application does not have access to window.localStorage in which case you will need to provide a way for the SJWT library to save, load, and remove tokens.

Parameters

save()

import {save} from 'sjwt';
save({
    publicData: {<Any valid json object>},
    privateData: {<Any valid json object>},
    overwrite: false,
    projectId: 'YOUR PROJECT ID',
});

The save method allows you to update what the currently logged in end-user has stored in publicData and/or in privateData. Currently both are only accessible to the end-user, but as the API evolves, publicData will eventually be accessible to anyone, while privateData will continue to be only accessible by the end-user. The entire data payload must be 1mb in size or less.

Parameters