A quick and easy node.js template project for an API with token-based authentication.
-
Clone repository.
-
Open a command prompt, navigate to the folder, and enter:
npm install -
Next, run the app by entering:
node app -
Browse to http://localhost:8080
-
Obtain a token.
POST /api/auth { username: user, password: pass }
-
Call API methods by including your token in the HTTP header or url.
Content-Type: application/json x-access-token: abc123
or
/api/method1?token=abc123 /api/method2?token=abc123
The url /api/auth allows you to generate an authentication token which can be used to access API methods.
To generate a token, call POST /api/auth. Include a username and password as a JSON object within the form data. The format is shown below.
{ username: 'user', password: 'pass' }You can also generate a token by including an existing valid token in the HTTP header or url.
The username and password can be validated against your database or other means. If successful, a JSON web token is returned in the response. The token contains an expiration time as configured.
Your code can store the token for subsequent calls to the API. Each API call should contain the token within the url or HTTP header.
The demo code includes a simple method for validating the username and password before generating a token. The template project simply checks the username and password against the one configured. You'll probably want to change this to check against your database or other method for validating a user.
By default, tokens expire after 20 minutes.
Since tokens have an expiration time, the client code should keep track of when the current token expires. Before expiring, the client can request a new token by making a POST request to /api/auth, including the existing token in the HTTP header or url (in place of sending a username/password in the post data). Otherwise, if the token expires, the client will need to login with a username/password to obtain a new token.
API methods can be added as routes within app.js. The code for each API method can be added within the handler. Several example API stub methods are provided.
Here is what an example API method looks like:
exports.method1 = function(req, res) {
res.json({
message: 'This is API method 1. Hello, ' + req.auth.username + '!'
});
};Pretty simple, right?
The request object contains a variable req.auth, which has the user information that logged into the application. You can use this to retrieve the username and any other information about the user that you store within the token. To add other info within the token, just change the user object that gets returned from loading your user.
Example API method 1. This method requires a valid token.
Example API method 2. This method requires a valid token.
Notice in the configuration file that the application uses process.env.VARIABLE_NAME to store sensitive values, such as the username, password, and token key. These values are passed into the node.js application at run-time via the command-line. This application is using the handy library dotenv to load values from .env instead of the command-line. This makes it easier to run the app during development.
If you want to keep the same process.env variables in your configuration, just make sure to provide those values when deploying to your server (i.e., Heroku config variables, etc).
MIT
Kory Becker