Skip to content

Javascript Library Reference

Installation

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

$ npm install --save @propelauth/javascript
$ yarn add @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 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({
    authUrl: "https://auth.yourdomain.com", // (1)
    enableBackgroundTokenRefresh: true, // (2)
})
  1. The base URL where your authentication pages are hosted. You can find this under the Frontend Integration section for your project.
  2. If true, periodically refresh the access token in the background. This helps ensure you always have a valid token ready to go. Default 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,
}

// 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
}

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.

Redirect to signup page

Redirects the user to the signup hosted authentication page.

authClient.redirectToSignupPage(options?: RedirectToLoginOptions)

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

Redirect to login page

Redirects the user to the login hosted authentication page.

authClient.redirectToLoginPage(options?: RedirectToLoginOptions)

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

Redirect to account page

Redirects the user to the account hosted authentication page, where they can view/modify their user information.

authClient.redirectToAccountPage()

Redirect to create org page

Redirects the user to the hosted authentication page where they can create organizations.

authClient.redirectToCreateOrgPage()

Redirect to org page

Redirects the user to an organization management hosted authentication page.

authClient.redirectToOrgPage(orgId?: string)

If orgId is specified, redirect to that organization's page. If none is specified, a default is chosen deterministically.

Listen for logged in or out events

Adds or removes an observer which is called whenever the user logs in or out.

authClient.addLoggedInChangeObserver(observer: (isLoggedIn: boolean) => void)
authClient.removeLoggedInChangeObserver(observer: (isLoggedIn: boolean) => void)

Destroy

Cleanup the auth client.

authClient.destroy()