There are four ways of authenticating:
We always use email and password to identify the user. The passwords are always one-way encrypted using bcrypt.
In a typical application, your front-end site would present a login page asking for the user's email and password. In addition, you would present a "Forgotten Password" link.
When the user submits their username and password, you would POST that data to the /login endpoint. If the login succeeds, the page will return their API key and bearer token.
Logging in will always delete the previous token and give you a new one.
POST http://localhost:4001/login
Data:
{
"email": "blah@blah.com",
"password": "TopSecret"
}
Successful Response (Status 200):
{
"user_id": "5dadbd7e2384ad419975e4a1",
"apikey": "<apikey>",
"token": "<token>",
"token_expires": "2025-11-21T21:26:20.671Z",
"refresh_token": "<refresh_token>",
"refresh_token_expires": "2025-12-21T21:26:20.671Z"
}
Failed Response (Status 401):
{
"status": "fail",
"message": "Authentication failed",
"err": "Incorrect email; email: <email>"
}
You can use your refresh_token to refresh a token, even if it's expired. By default, refresh tokens last 30 days, whereas tokens last 24 hours.
Note that the response is almost identical to the /login endpoint, except it doesn't have the apikey.
POST http://localhost:4001/refresh
Header:
{
"Authorization": "Bearer <refresh token>",
}
Successful Response (Status 200):
{
"user_id": "5dadbd7e2384ad419975e4a1",
"token": "<token>",
"token_expires": "2025-11-21T21:26:20.671Z",
"refresh_token": "<refresh_token>",
"refresh_token_expires": "2025-12-21T21:26:20.671Z"
}
Failed Response (Status 401):
{
"status": "fail",
"message": "Authentication failed",
"err": "Incorrect email; email: <email>"
}
This will immeditately expire the token.
POST or GET http://localhost:4001/login/logout
Send the user an email with their JWT embedded so that they can reset their password
POST http://localhost:4001/login/recover
Data:
{
"email": "blah@blah.com"
}
Successful Response (200):
{
"status": "ok",
"message": "Sent recovery email"
}
Failed Response (403):
{
"status": "fail",
"message": "Unauthorized",
"err": "Could not find email"
}
Note: You will still have to build the password reset page on your front end.
A Javascript Web Token can be used to log the user in through a URL.
POST http://localhost:4001/login/getjwt
Data:
{
"email": "blah@blah.com"
}
Successful Response (200):
{
"status": "ok",
"jwt": "<jwt>"
}
Failed Response (403):
{
"status": "fail",
"message": "Unauthorized",
"err": "Could not find email"
}
Basic auth encodes (NOTE: NOT encrypts) your username and password and sends it as part of the header. You can use Basic Auth to authenticate yourself at any time.
WARNING: You must only use basic auth over SSL, since it is trivial to decode the username and password. In fact, you should use SSL for everything, anyway.
A basic auth is created by base64-encoding your username and password, separated by a colon.
Eg. echo "blah@blah.com:password" | base64 would generate a basic auth token on the command line. (In this case, it would encode to YmxhaEBibGFoLmNvbTpwYXNzd29yZAo=.)
However, echo "YmxhaEBibGFoLmNvbTpwYXNzd29yZAo=" | base64 --decode would reveal the uesrname and password, which is why it's not safe to use it on an unencrypted connection.
Header: Authorization: Basic <your basic token>
This is the preferred method of authenticating.
Bearer tokens are ephemeral tokens that will expire in a certain time period. When a user logs out of a session, they will be destroyed.
Header: Authorization: Bearer <your bearer token>
The API Key is a permanent key that doesn't expire. It can be used by adding ?apikey=<apikey> to the end of any request, or sending apikey: <apikey> in the header.