Javascript Reference - PropelAuth Docs

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 enable 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

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.

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

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

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.

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

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

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.

Properties

The user's unique ID

The user's email address

The timestamp of when the user was created

The user's first name

The user's last name

The user's username

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

The URL of the user's profile picture

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.

Whether the user has 2FA authentication enabled

Whether the user can create organizations

The user's legacy user ID. This is only set if you migrated from an external source. See Migrating Users 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:

Returns the OrgMemberInfoClass for the given org ID

Returns the OrgMemberInfoClass for the given org name

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

Returns all orgs that the user is a member of

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

Whether the user has the given role in the given org

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

Whether the user has the given permission in the given org

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

The ID of the organization

The name of the organization

The URL-safe name of the organization

The role of the user within this organization

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

The permissions of the user within this organization

A JSON blob of the org's metadata

Whether the user has the given role in this organization

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

Whether the user has the given permission in this organization

Whether the user has all the given permissions in this organization

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

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

Whether the user has the given role in the given org

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

Whether the user has the given permission in the given org

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

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

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

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

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

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

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

The ID of the organization to get the URL for

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

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

The ID of the organization to get the URL for

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

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

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

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

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

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

The ID of the organization to get the URL for

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

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

The ID of the organization to get the URL for

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

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()