Node Reference
PropelAuth's Node library provides all the building blocks you need to add authentication to your Node projects. You should prefer the Express, Next.js App Router, Next.js Pages Router libraries if you are using those frameworks, as they provide a more first-class experience, however, this library can be used in any Node project.
Installation
npm install @propelauth/node
Initialize
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.
In serverless environments, it's beneficial to skip the fetch, in which case you can pass in manualTokenVerificationMetadata
instead of having the library fetch it.
import { initBaseAuth } from '@propelauth/node';
const {
validateAccessTokenAndGetUser,
fetchUserMetadataByUserId,
// ...
} = initBaseAuth({
authUrl: "REPLACE_ME",
apiKey: "REPLACE_ME",
});
Protect API Routes
After initializing auth, you can verify access tokens by passing in the Authorization header (formatted Bearer TOKEN
) to validateAccessTokenAndGetUser
.
You can see more information about the User object returned in User.
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}`);
}
Verifying the access token doesn't require an external request.
Authorization / Organizations
You can also verify which organizations the user is in, and which roles and permissions they have in each organization. For that, we have functions like:
validateAccessTokenAndGetUserWithOrgInfo
validateAccessTokenAndGetUserWithOrgInfoWithMinimumRole
validateAccessTokenAndGetUserWithOrgInfoWithExactRole
validateAccessTokenAndGetUserWithOrgInfoWithPermission
validateAccessTokenAndGetUserWithOrgInfoWithAllPermissions
const authorizationHeader = // Get the Authorization header from an HTTP request
const orgId = // Get the orgId from the HTTP request
try {
const { user, orgMemberInfo } = await validateAccessTokenAndGetUserWithOrgInfo(
authorizationHeader,
{ orgId }
);
} catch (err) {
if (err instanceof UnauthorizedException) {
// can return a 401, the user is invalid
} else if (err instanceof ForbiddenException) {
// can return a 403, the user is valid,
// but isn't in that org, or doesn't have the proper role/permissions
}
}
User
The User object contains information about the user that made the request.
- Name
userId
- Type
- string
- Description
The unique id of the user.
- Name
email
- Type
- string
- Description
The email of the user.
- Name
firstName
- Type
- string
- Description
The first name of the user.
- Name
lastName
- Type
- string
- Description
The last name of the user.
- Name
username
- Type
- string
- Description
The username of the user.
- Name
legacyUserId
- Type
- string
- Description
If the user was migrated using our Migration API, this will be the id of the user in the legacy system.
- Name
impersonatorUserId
- Type
- string
- Description
If the user is being impersonated, this is id of the user that impersonated them.
- Name
properties
- Type
- {[key: string]: unknown}
- Description
A dictionary of custom properties associated with the user.
- Name
orgIdToOrgMemberInfo
- Type
- {[orgId: string]: OrgMemberInfo}
- Description
A dictionary mapping from organization id to OrgMemberInfo object.
OrgMemberInfo
The OrgMemberInfo object contains information about the user's membership in an organization.
- Name
orgId
- Type
- string
- Description
The unique id of the organization.
- Name
orgName
- Type
- string
- Description
The name of the organization.
- Name
orgMetadata
- Type
- object
- Description
The metadata associated with the organization.
- Name
userAssignedRole
- Type
- string
- Description
The role of the user in the organization.
- Name
userPermissions
- Type
- string[]
- Description
A list of permissions the user has in the organization, based on their role.
- Name
isRole
- Type
- fn(role: string) -> boolean
- Description
A function that returns true if the user has the specified role in the organization.
- Name
isAtLeastRole
- Type
- fn(role: string) -> boolean
- Description
A function that returns true if the user has at least the specified role in the organization.
- Name
hasPermission
- Type
- fn(permission: string) -> boolean
- Description
A function that returns true if the user has the specified permission in the organization.
- Name
hasAllPermissions
- Type
- fn(permissions: string[]) -> boolean
- Description
A function that returns true if the user has all of the specified permissions in the organization.
Calling Backend APIs
You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.
const magicLink = await auth.createMagicLink({
email: "user@customer.com"
})
See the API Reference for more information.