Express Library Reference

const propelAuth = require("@propelauth/express");
const {
  requireUser,
  optionalUser,
  requireOrgMember,
  requireOrgMemberWithMinimumRole,
  requireOrgMemberWithExactRole,
  requireOrgMemberWithPermission,
  requireOrgMemberWithAllPermissions,
  fetchUserMetadataByUserId,
  fetchUserMetadataByEmail,
  fetchUserMetadataByUsername,
  fetchBatchUserMetadataByUserIds,
  fetchBatchUserMetadataByEmails,
  fetchBatchUserMetadataByUsernames,
  fetchOrg,
  fetchOrgByQuery,
  fetchUsersByQuery,
  fetchUsersInOrg,
  createUser,
  updateUserMetadata,
  updateUserEmail,
  createMagicLink,
  migrateUserFromExternalSource,
  createOrg,
  addUserToOrg,
  deleteUser,
  disableUser,
  enableUser,
  allowOrgToSetupSamlConnection,
  disallowOrgToSetupSamlConnection,
} = propelAuth.initAuth({
  // If true, error messages returned to the user will be detailed.
  // It's useful for debugging, but a good idea to turn off in production.
  debugMode: true,
  // You can find your Auth URL and API key under the Backend Integration
  //   section for your project at https://app.propelauth.com.
  authUrl: "https://auth.yourdomain.com",
  apiKey: "YOUR_API_KEY",
});

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

const { requireUser } = require("./propelauth");

app.get("/hello", requireUser, (req, res) => {
  res.text("Hello user with ID " + req.user.userId);
});

app.get("/hello", optionalUser, (req, res) => {
  if (req.user) {
    res.text("Hello user with ID " + req.user.userId);
  } else {
    res.text("Hello anonymous");
  }
});

// Assuming a Role structure of Owner => Admin => Member

app.get(
  "/org/:orgId/admin",
  requireOrgMemberWithExactRole({ role: "Admin" }),
  (req, res) => {
    res.text("You are an Admin of " + req.org.orgName);
  }
);

app.get(
  "/org/:orgId/admin_or_owner",
  requireOrgMemberWithMinimumRole({ minimumRequiredRole: "Admin" }),
  (req, res) => {
    res.text("You are an Admin of " + req.org.orgName);
  }
);

app.get(
  "/org/:orgId/billing",
  requireOrgMemberWithPermission({ permission: "can_view_billing" }),
  (req, res) => {
    // TODO: view billing
  }
);

{
    userId:            "e9d3520f-836e-403c-82c2-09843517e1ce",
    email:             "user@example.com",
    emailConfirmed:    true,
    hasPassword:       true,

    username:          "example",
    firstName:         "first",
    lastName:          "last",
    pictureUrl:        "https://...",

    // True if the user's account is locked for security purposes.
    locked:            false,
    enabled:           true,
    mfaEnabled:        false,

    createdAt:         1645131680,
    lastActiveAt:      1650654711,

    // Only returned if includeOrgs = true
    orgIdToOrgInfo: {
        "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4" : {
            orgId: "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4",
            orgName: "ExampleOrganization",
            userAssignedRole: "Owner",
        }
    },

    // Only returned if user was migrated from an external system
    legacyUserId:    "507f191e810c19729de860ea"
}

function fetchBatchUserMetadataByUserIds(userIds: string[], includeOrgs?: boolean): Promise<{ [userId: string]: UserMetadata }>

{
    "e9d3520f-836e-403c-82c2-09843517e1ce": {
        userId:            "e9d3520f-836e-403c-82c2-09843517e1ce",
        email:             "user@example.com",
        emailConfirmed:    true,
        hasPassword:       true,

        username:          "example",
        firstName:         "first",
        lastName:          "last",
        pictureUrl:        "https://...",

        // True if the user's account is locked for security purposes.
        locked:            false,
        enabled:           true,
        mfaEnabled:        false,

        createdAt:         1645131680,
        lastActiveAt:      1650654711,

        // Only returned if includeOrgs = true
        orgIdToOrgInfo: {
            "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4" : {
                orgId: "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4",
                orgName: "ExampleOrganization",
                userAssignedRole: "Owner",
            }
        },

        // Only returned if user was migrated from an external system
        legacyUserId:    "507f191e810c19729de860ea"
    },
    // other user_ids
}

function fetchBatchUserMetadataByEmails(emails: string[], includeOrgs?: boolean): Promise<{ [email: string]: UserMetadata }>

function fetchBatchUserMetadataByUsernames(usernames: string[], includeOrgs?: boolean): Promise<{ [username: string]: UserMetadata }>

function fetchUsersByQuery(usersQuery: UsersQuery): Promise<UsersPagedResponse>

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

{
    "totalUsers": 103,
    "currentPage": 0,
    "pageSize": 10,
    "hasMoreResults": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response
    }]
}

function fetchUsersInOrg(usersInOrgQuery: UsersInOrgQuery): Promise<UsersPagedResponse>

// Example
const usersResponse = await auth.fetchUsersInOrg({
    orgId: req.params.orgId,
    pageNumber: req.params.pageNumber,
})

{
    "totalUsers": 43,
    "currentPage": 0,
    "pageSize": 10,
    "hasMoreResults": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response, all in the specified organization
    }]
}

function createUser(createUserRequest: CreateUserRequest): Promise<User>

{
    "userId": "b5f667fb-e51a-49c6-a396-711e62948689"
}

function migrateUserFromExternalSource(migrateUserFromExternalSourceRequest: MigrateUserFromExternalSourceRequest): Promise<User>

{
    "userId": "b5f667fb-e51a-49c6-a396-711e62948689"
}

function createMagicLink(createUserRequest: CreateMagicLinkRequest): Promise<MagicLink>

{
    "url": "https://auth.yourdomain.com/..."
}

function createAccessToken(createAccessTokenRequest: CreateAccessTokenRequest): Promise<AccessToken>

{
    "access_token": "..."
}

// Returns true if it was successful, false if the user was not found
function updateUserEmailWrapper(userId: string, updateUserEmailRequest: UpdateUserEmailRequest): Promise<boolean>

// Returns true if it was successful, false if the user was not found
function updateUserMetadata(userId: string, updateUserMetadataRequest: UpdateUserMetadataRequest): Promise<boolean>

// Returns true if it was successful, false if the user was not found
function updateUserPassword(userId: string, updateUserPasswordRequest: UpdateUserPasswordRequest): Promise<boolean>

function deleteUser(userId: string): Promise<boolean>

function disableUser(userId: string): Promise<boolean>

function enableUser(userId: string): Promise<boolean>

function fetchOrg(orgId: string): Promise<Org | null>

{
    "orgId": "d488996d-8ccc-4101-b5f2-131f5f09ddb6"
    "name": "OneOfYourCustomers"
}

function fetchOrgsByQuery(orgQuery: OrgQuery): Promise<OrgQueryResponse>

{
    "totalOrgs": 21,
    "currentPage": 0,
    "pageSize": 10,
    "hasMoreResults": true,
    "orgs": [{
        "orgId": "d488996d-8ccc-4101-b5f2-131f5f09ddb6",
        "name": "OneOfYourCustomers"
    }, {
        // There will be 10 orgs in this response
    }]
}

function createOrg(createOrgRequest: CreateOrgRequest): Promise<Org>

{
    "orgId": "d488996d-8ccc-4101-b5f2-131f5f09ddb6"
}

function addUserToOrg(addUserToOrgRequest: AddUserToOrgRequest): Promise<boolean>

function allowOrgToSetupSamlConnection(orgId: string): Promise<boolean>

function disallowOrgToSetupSamlConnection(orgId: string): Promise<boolean>