Node Backend Integration

For the full Node Library Reference, click here. This library is useful if you are in a pure node environment, like AWS Lambda. If you are using a framework like Express, you should prefer to use our Express library.

​

Quick example

The following example validates an Authorization HTTP header was sent from a logged-in user.

const propelAuth = require("@propelauth/node");
const { validateAccessTokenAndGetUser } = propelAuth.initBaseAuth({
  // You can find your Auth URL and API key under the Backend Integration
  //   section for your project at https://app.propelauth.com.
  authUrl: "YOUR_AUTH_URL",
  apiKey: "YOUR_API_KEY",
});

const authorizationHeader = // Get the Authorization header from an HTTP request
validateAccessTokenAndGetUser(authorizationHeader).then(
  (user) => {
    console.log(`Got request from user ${user.userId}`);
  },
  (err) => {
    // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
    console.log(`Unauthorized request ${err}`);
  }
);

​

How it works

For a detailed description of what’s going on under the hood, see here.

​

Installation

In your Node app, install the @propelauth/node library.

$ npm install --save @propelauth/node

​

Initialize

In a new file, add the following:

// propelauth.js
const propelAuth = require("@propelauth/node");
module.exports = propelAuth.initBaseAuth({
  authUrl: "https://auth.yourdomain.com",
  apiKey: "YOUR_API_KEY",
});

initBaseAuth performs a one-time initialization of the library. It will verify your apiKey is correct and fetch the metadata needed to verify access tokens in validateAccessTokenAndGetUser and validateAccessTokenAndGetUserWithOrgInfo.

​

Protect API routes

​

validateAccessTokenAndGetUser

This function takes in the Authorization HTTP header and verifies the request was made by a valid user. It expects the header to be in the format Bearer ACCESS_TOKEN. If the Authorization HTTP header is malformed or doesn’t contain a valid access token, an UnauthorizedException is thrown.

const authorizationHeader = // Get the Authorization header from an HTTP request
try {
    const user = await validateAccessTokenAndGetUser(authorizationHeader)
    console.log(`Got request from user ${user.userId}`);
} catch (err) {
    // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user
    console.log(`Unauthorized request ${err}`);
}

The user object looks like:

The values of orgIdToOrgMemberInfo are OrgMemberInfo’s, with the following fields/functions:

​

validateAccessTokenAndGetUserWithOrgInfo

This function will verify that a request was made by a valid user AND that user is in an organization.

It returns an object with two fields:

{
    user: //...
    orgMemberInfo: //...
}

You can see the structure of the user and orgMemberInfo objects above: validateAccessTokenAndGetUser.

​

Roles and Permissions

A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.

Roles allow you to control what different users can do within your product. If you want to check a user’s role, you can use validateAccessTokenAndGetUserWithOrgInfoWithExactRole or validateAccessTokenAndGetUserWithOrgInfoWithMinimumRole.

Permissions are arbitrary strings associated with a role. For example, can_view_billing, ProductA::CanCreate, and ReadOnly are all valid permissions. The PropelAuth dashboard allows you to set up these permissions.

You can use validateAccessTokenAndGetUserWithOrgInfoWithPermission or validateAccessTokenAndGetUserWithOrgInfoWithAllPermissions to check for a given permission.

All of these functions, just like validateAccessTokenAndGetUserWithOrgInfo, will take in an authorization header and an organization ID. The last parameter is either a role, permission, or list of permissions depending on the function.

​

API calls

In addition to protecting API routes, you can make requests to PropelAuth to fetch more information about your users or organizations. You can also create new users, update user metadata, and more.

// Example
const usersResponse = await fetchUsersByQuery({
  emailOrUsername: "@example.com",
  orderBy: "LAST_ACTIVE_AT_DESC",
});
for (const user of userResponse.users) {
  console.log("Found user " + user);
}

See Node Library Reference for more information on available functionality.

​

Next Steps

Done with your backend? Next you can deploy to production.