Javascript Library Reference

Installation

In your application, install the @propelauth/javascript library.

$ npm install --save @propelauth/javascript

and then you can import it

import { createClient } from "@propelauth/javascript";

Alternatively, you can use a CDN:

<script
  src="https://www.unpkg.com/@propelauth/javascript@2.0.0/dist/javascript.min.js"
  integrity="sha384-CnMW/GT96q1vxl3xq1fIbUrmXpDIsXVtY+/FpJW+rMSCgjlOWpbVfs5G0dg2bMN5"
  crossorigin="anonymous"
></script>

then a global PropelAuth object will be created, and you can call createClient from it:

<script>
  PropelAuth.createClient({...});
</script>

createClient

Creates an authentication client which manages your user’s access token, fetches user information, and provides other useful authentication functions.

The client also refreshes auth information when a user switches focus to your tab or reconnects (if they were offline).

const authClient = createClient({
  // The base URL where your authentication pages are hosted.
  // You can find this under the Frontend Integration section for your project.
  authUrl: "https://auth.yourdomain.com",

  // If true, periodically refresh the access token in the background.
  // This helps ensure you always have a valid token ready to go. Default true.
  enableBackgroundTokenRefresh: true,
});

AuthenticationInfo and User metadata

There are a few key types that this library uses, here are their signatures:

type AuthenticationInfo = {
    // An access token for the current logged in user
    accessToken: string,
    // When the access token will no longer be valid, in seconds.
    expiresAtSeconds: number,
    // A collection of functions for managing organization membership information for the current user
    orgHelper: OrgHelper
    // A collection of functions for checking roles (RBAC) and permissions for the current user
    accessHelper: AccessHelper
    // For all organizations the current user is a member of,
    //   this provides a mapping from their ids to metadata about them
    // You should prefer orgHelper and accessHelper to orgIdToOrgMemberInfo.
    orgIdToOrgMemberInfo?: OrgIdToOrgMemberInfo,

    // Metadata about the current logged in user
    user: User,

    // If someone on your team is impersonating another user, this will be set to the employee's ID
    // By default, user impersonation is turned off and this will be undefined
    impersonatorUserId?: string
}

// Metadata about the current logged in user
type User = {
    userId: string

    email: string
    emailConfirmed: boolean,

    hasPassword: boolean,

    username?: string
    firstName?: string,
    lastName?: string,
    pictureUrl?: string,

    locked: boolean,
    enabled: boolean,
    mfaEnabled: boolean,

    createdAt: number,
    lastActiveAt: number,

    legacyUserId?: string

    properties: { [key: string]: unknown }
}

Organizations, Roles, and Authorization

Here are more types that you can find in the AuthenticationInfo object

type OrgHelper = {
    // returns all orgs that the user is a member of
    getOrgs: () => OrgMemberInfo[],
    // returns all org ids that the user is a member of
    getOrgIds: () => string[],
    // returns org information for a given orgId
    getOrg: (orgId: string) => OrgMemberInfo | undefined,
    // returns org information for a given org by name
    getOrgByName: (orgName: string) => OrgMemberInfo | undefined,
}

type AccessHelper = {
    isRole: (orgId: string, role: string) => boolean
    isAtLeastRole: (orgId: string, role: string) => boolean
    hasPermission: (orgId: string, permission: string) => boolean
    hasAllPermissions: (orgId: string, permissions: string[]) => boolean
}

type OrgMemberInfo = {
    orgId: string,
    orgName: string,
    urlSafeOrgName: string
    // The role of the user within this organization
    userAssignedRole: string
    userPermissions: string[]
}

Get current user information

authClient.getAuthenticationInfoOrNull(forceRefresh?: boolean): Promise<AuthenticationInfo | null>

If the user is logged in, this method returns authentication information about them, including their access token, user metadata, and, for B2B applications, organization information. See AuthenticationInfo schema for the full schema. Otherwise, this method returns null.

The promise will generally resolve immediately, without making an external request, unless our current access token is stale in which case it will fetch a new one.

If forceRefresh is true, this method will always fetch a new token. The default is false.

Logout

Logs the current user out.

authClient.logout(redirectAfterLogout: boolean): Promise<void>

If redirectAfterLogout is true, redirect the user to the configured logout URL. This is configured in the Frontend Integration section of your project.

Redirects the user to the signup page.

authClient.redirectToSignupPage(options?: RedirectToSignupOptions)

export interface RedirectToSignupOptions {
    // This must be a full URL and can only be a URL for a domain you have verified
    postSignupRedirectUrl: string
}