Frontend
BackendĀ 

Javascript

The @propelauth/javascript library is designed for any frontend application. While you should prefer a more specific framework, like React, whenever possible, this library has been used in applications with Svelte, Angular, Vue, and more.


Installation and Usage

npm install @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.11/dist/javascript.min.js" 
    integrity="sha384-FENNH2f7QuQvkZJBL7jebLr0OtYKgTA2iq+C5g3VXXX7SBwWmeMMoc+pBBtcn76G" 
    crossorigin="anonymous"></script>

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

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

Using the Javascript library

You'll create a client using the createClient function, and then you can use the client to get information about the current user.

You can also enabled background token refresh, which will automatically refresh the user's information periodically and on key events (e.g. user switches tabs, reconnects to the internet, etc).


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,
});

getAuthenticationInfoOrNull

If the user is logged in, this method returns an AuthenticationInfo object with information about the user. Otherwise, this method returns null.

The promise will generally resolve immediately, unless our current information is stale in which case it will make an API request.

Arguments

  • Name
    forceRefresh
    Type
    boolean
    Description

    If true, the client will make an API request to get the latest information. Otherwise, it will use the cached information if it is still valid.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const authInfo = await authClient.getAuthenticationInfoOrNull()
if (authInfo) {
    console.log("User is logged in as", authInfo.user.email)
} else {
    console.log("User is not logged in")
}

AuthenticationInfo

AuthenticationInfo is an object that contains information about the current user. It is returned from getAuthenticationInfoOrNull.

  • Name
    accessToken
    Type
    string
    Description

    The user's access token. You can use this to make API requests to your backend.

  • Name
    user
    Type
    User
    Description

    The user's information. See User for more information.

  • Name
    userClass
    Type
    UserClass
    Description

    Similar to User, but instead of just being a JSON object, this is a class with helper functions (e.g. getOrg, isImpersonating). See UserClass for more information.

  • Name
    orgHelper
    Type
    OrgHelper
    Description

    A helper class for accessing the user's organization information. See OrgHelper for more information.

  • Name
    accessHelper
    Type
    AccessHelper
    Description

    A helper class for accessing the user's roles and permissions. See AccessHelper for more information.

  • Name
    impersonatorUserId
    Type
    string | undefined
    Description

    If the current user is being impersonated, this will be the ID of the impersonator. See User Impersonation for more information.


User

This is the object that contains all the information about the current user. It is within the AuthenticationInfo returned from getAuthenticationInfoOrNull.

Properties

  • Name
    userId
    Type
    string
    Description

    The user's unique ID

  • Name
    email
    Type
    string
    Description

    The user's email address

  • Name
    createdAt
    Type
    number
    Description

    The timestamp of when the user was created

  • Name
    firstName
    Type
    string | undefined
    Description

    The user's first name

  • Name
    lastName
    Type
    string | undefined
    Description

    The user's last name

  • Name
    username
    Type
    string | undefined
    Description

    The user's username

  • Name
    properties
    Type
    object | undefined
    Description

    Additional properties set on the user. See User Properties for more information.

  • Name
    pictureUrl
    Type
    string | undefined
    Description

    The URL of the user's profile picture

  • Name
    hasPassword
    Type
    boolean
    Description

    Whether the user has a password set. This will be false for users that signed up with a social provider (e.g. Google, Facebook), magic link, or SAML.

  • Name
    hasMfaEnabled
    Type
    boolean
    Description

    Whether the user has 2FA authentication enabled

  • Name
    canCreateOrgs
    Type
    boolean
    Description

    Whether the user can create organizations

  • Name
    legacyUserId
    Type
    string | undefined
    Description

    The user's legacy user ID. This is only set if you migrated from an external source. See Migrating Users for more information.

  • Name
    impersonatorUserId
    Type
    boolean
    Description

    If the current user is being impersonated, this will be the ID of the impersonator. See User Impersonation for more information.


UserClass

Similar to User, but instead of just being a JSON object, this is a class with helper functions (e.g. getOrg, isImpersonating). It is within the AuthenticationInfo returned from getAuthenticationInfoOrNull.

Properties

In addition to all the properties on User, this contains:

  • Name
    getOrg
    Type
    (orgId: string) => OrgMemberInfoClass | undefined
    Description

    Returns the OrgMemberInfoClass for the given org ID

  • Name
    getOrgByName
    Type
    (orgName: string) => OrgMemberInfoClass | undefined
    Description

    Returns the OrgMemberInfoClass for the given org name

  • Name
    getUserProperty
    Type
    (key: string) => unknown | undefined
    Description

    Returns the value of a user property. See User Properties for more information.

  • Name
    getOrgs
    Type
    () => OrgMemberInfoClass[]
    Description

    Returns all orgs that the user is a member of

  • Name
    isImpersonating
    Type
    () => boolean
    Description

    Whether the current user is being impersonated by someone else. See User Impersonation for more information.

  • Name
    isRole
    Type
    (orgId: string, role: string) => boolean
    Description

    Whether the user has the given role in the given org

  • Name
    isAtLeastRole
    Type
    (orgId: string, role: string) => boolean
    Description

    Whether the user has at least the given role in the given org

  • Name
    hasPermission
    Type
    (orgId: string, permission: string) => boolean
    Description

    Whether the user has the given permission in the given org

  • Name
    hasAllPermissions
    Type
    (orgId: string, permissions: string[]) => boolean
    Description

    Whether the user has all the given permissions in the given org

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const authInfo = await authClient.getAuthenticationInfoOrNull()
if (!authInfo) {
    console.log("User is not logged in")
    return;
}

console.log("User is logged in as", authInfo.userClass.email)
if (authInfo.userClass.isImpersonating()) {
    console.log("User is being impersonated by", authInfo.userClass.impersonatorUserId)
}

OrgMemberInfoClass

Similar to OrgMemberInfo, but instead of just being a JSON object, this is a class with helper functions (e.g. isRole, hasPermission). It is returned from functions on the UserClass like UserClass.getOrg and UserClass.getOrgByName.

Properties

  • Name
    orgId
    Type
    string
    Description

    The ID of the organization

  • Name
    orgName
    Type
    string
    Description

    The name of the organization

  • Name
    urlSafeOrgName
    Type
    string
    Description

    The URL-safe name of the organization

  • Name
    userAssignedRole
    Type
    string
    Description

    The role of the user within this organization

  • Name
    userInheritedRolesPlusCurrentRole
    Type
    string[]
    Description

    The role of the user within this organization plus each inherited role

  • Name
    userPermissions
    Type
    string[]
    Description

    The permissions of the user within this organization

  • Name
    orgMetadata
    Type
    object
    Description

    A JSON blob of the org's metadata

  • Name
    isRole
    Type
    (role: string) => boolean
    Description

    Whether the user has the given role in this organization

  • Name
    isAtLeastRole
    Type
    (role: string) => boolean
    Description

    Whether the user has at least the given role in this organization

  • Name
    hasPermission
    Type
    (permission: string) => boolean
    Description

    Whether the user has the given permission in this organization

  • Name
    hasAllPermissions
    Type
    (permissions: string[]) => boolean
    Description

    Whether the user has all the given permissions in this organization

  • Name
    orgRoleStructure
    Type
    string
    Description

    The role structure set for your project. See multi role per user for more information.

  • Name
    userAssignedAdditionalRoles
    Type
    string[]
    Description

    If using multiple roles per user, returns an array of roles that the user belongs to. Excludes the userAssignedRole.

const org = userClass.getOrg("my-org-id")
const isAdmin = org?.isRole("Admin")
if (isAdmin) {
    console.log("User is an admin in", org.orgName)
}

OrgHelper

OrgHelper is a helper class for accessing the user's organization information. It is within the AuthenticationInfo returned from getAuthenticationInfoOrNull.

Signature

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 OrgMemberInfo = {
    orgId: string,
    orgName: string,
    urlSafeOrgName: string
    // The role of the user within this organization
    userAssignedRole: string
    userPermissions: string[]
}

Example

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const authInfo = await authClient.getAuthenticationInfoOrNull()
if (!authInfo) {
    console.log("User is not logged in")
    return;
}

const orgs = authInfo.orgHelper.getOrgs()
for (const org of orgs) {
    console.log("User is a", org.userAssignedRole, "in", org.orgName)
}

AccessHelper

A helper class for accessing the user's roles and permissions. It is within the AuthenticationInfo returned from getAuthenticationInfoOrNull.

Properties

  • Name
    isRole
    Type
    (orgId: string, role: string) => boolean
    Description

    Whether the user has the given role in the given org

  • Name
    isAtLeastRole
    Type
    (orgId: string, role: string) => boolean
    Description

    Whether the user has at least the given role in the given org

  • Name
    hasPermission
    Type
    (orgId: string, permission: string) => boolean
    Description

    Whether the user has the given permission in the given org

  • Name
    hasAllPermissions
    Type
    (orgId: string, permissions: string[]) => boolean
    Description

    Whether the user has all the given permissions in the given org

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const authInfo = await authClient.getAuthenticationInfoOrNull()
if (!authInfo) {
    console.log("User is not logged in")
    return;
}

const isAdmin = authInfo.accessHelper.isAtLeastRole("my-org-id", "Admin")
console.log("User is an admin:", isAdmin)

logout

Logs the current user out.

Arguments

  • Name
    redirectAfterLogout *
    Type
    boolean
    Description

    If true, the user will be redirected to the login page after logging out.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

await authClient.logout(true)

getSignupPageUrl

Gets the URL of the signup page. This is useful if you want to link to the signup page from your application.

It takes in one optional argument which can control features like where the user returns to after logging in.

Arguments

  • Name
    postSignupRedirectUrl
    Type
    string
    Description

    The URL to redirect the user to after they sign up. Set the default in your Dashboard.

  • Name
    userSignupQueryParameters
    Type
    object
    Description

    Query parameters to add to the signup URL.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const signupPageUrl = authClient.getSignupPageUrl({
    postSignupRedirectUrl: window.location.href,
    userSignupQueryParameters: {
        "ref": "my-cool-blog-post"
    }
})

getLoginPageUrl

Gets the URL of the login page. This is useful if you want to link to the login page from your application.

It takes in one optional argument which can control features like where the user returns to after logging in.

Arguments

  • Name
    postLoginRedirectUrl
    Type
    string
    Description

    The URL to redirect the user to after they log in. Set the default in your Dashboard.

  • Name
    userSignupQueryParameters
    Type
    object
    Description

    Query parameters to add to the login URL.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const loginPageUrl = authClient.getLoginPageUrl({
    postLoginRedirectUrl: window.location.href,
    userSignupQueryParameters: {
        "ref": "my-cool-blog-post"
    }
})

getAccountPageUrl

Gets the URL of the account page. This is useful if you want to link to the account page from your application.

Arguments

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const accountPageUrl = authClient.getAccountPageUrl({
    redirectBackToUrl: window.location.href
})

getOrgPageUrl

Gets the URL of the organization page for a given org ID. If an org ID is not provided, one is chosen automatically.

Arguments

  • Name
    orgId
    Type
    string
    Description

    The ID of the organization to get the URL for

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const orgPageUrl = authClient.getOrgPageUrl("my-org-id", {
    redirectBackToUrl: window.location.href
})

getCreateOrgPageUrl

Gets the URL of the create organization page. This is useful if you want to link to the create organization page from your application.

Arguments

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const createOrgPageUrl = authClient.getCreateOrgPageUrl({
    redirectBackToUrl: window.location.href
})

getSetupSAMLPageUrl

Gets the URL of a page to setup SAML for the given org ID.

Arguments

  • Name
    orgId *
    Type
    string
    Description

    The ID of the organization to get the URL for

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const setupSAMLPageUrl = authClient.getSetupSAMLPageUrl("my-org-id", {
    redirectBackToUrl: window.location.href
})

redirectToSignupPage

Redirects the user to the signup page. This is useful if you want to redirect the user to the signup page from your application.

It takes in one optional argument which can control features like where the user returns to after logging in.

Arguments

  • Name
    postSignupRedirectUrl
    Type
    string
    Description

    The URL to redirect the user to after they sign up. Set the default in your Dashboard.

  • Name
    userSignupQueryParameters
    Type
    object
    Description

    Query parameters to add to the signup URL.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToSignupPage({
    postSignupRedirectUrl: window.location.href,
    userSignupQueryParameters: {
        "ref": "my-cool-blog-post"
    }
})

redirectToLoginPage

Redirects the user to the login page. This is useful if you want to redirect the user to the login page from your application.

It takes in one optional argument which can control features like where the user returns to after logging in.

Arguments

  • Name
    postLoginRedirectUrl
    Type
    string
    Description

    The URL to redirect the user to after they log in. Set the default in your Dashboard.

  • Name
    userSignupQueryParameters
    Type
    object
    Description

    Query parameters to add to the login URL.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToLoginPage({
    postLoginRedirectUrl: window.location.href,
    userSignupQueryParameters: {
        "ref": "my-cool-blog-post"
    }
})

redirectToAccountPage

Redirects the user to the account page. This is useful if you want to redirect the user to the account page from your application.

Arguments

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToAccountPage({
    redirectBackToUrl: window.location.href
})

redirectToOrgPage

Redirects the user to the organization page for a given org ID. If an org ID is not provided, one is chosen automatically.

Arguments

  • Name
    orgId
    Type
    string
    Description

    The ID of the organization to get the URL for

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToOrgPage("my-org-id", {
    redirectBackToUrl: window.location.href
})

redirectToCreateOrgPage

Redirects the user to the create organization page. This is useful if you want to redirect the user to the create organization page from your application.

Arguments

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToCreateOrgPage({
    redirectBackToUrl: window.location.href
})

redirectToSetupSAMLPage

Redirects the user to a page to setup SAML for the given org ID.

Arguments

  • Name
    orgId *
    Type
    string
    Description

    The ID of the organization to get the URL for

  • Name
    redirectBackToUrl
    Type
    string
    Description

    The URL to redirect the user to when they click the back button on the account page

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

authClient.redirectToSetupSAMLPage("my-org-id", {
    redirectBackToUrl: window.location.href
})

getAccessTokenForOrg

A function that will return an access token that only includes the metadata for the provided org, as well as the user's metadata. Recommended for use with Active Org or to shorten the length of the access token.

Arguments

  • Name
    orgId *
    Type
    string
    Description

    The ID of the organization to get an access token for.

import {createClient} from "@propelauth/javascript"
const authClient = createClient({...})

const orgAccessToken = await authClient.getAccessTokenForOrg("my-org-id")

Logged In Events

To be notified when the user logs in or out, you can add an event listener:

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

Access Token Events

To be notified when the access token changes, you can add an event listener:

addAccessTokenChangeObserver(observer: (accessToken: string | undefined) => void): void
removeAccessTokenChangeObserver(observer: (accessToken: string | undefined) => void): void

destroy

Cleanup the client and stop all background processes.

authClient.destroy()