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.
Redirect to signup page
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
}
Or you can get the URL for the page with:
authClient.getSignupPageUrl(options?: RedirectToSignupOptions)
Redirect to login page
Redirects the user to the login 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
}
Or you can get the URL for the page with:
authClient.getLoginPageUrl(options?: RedirectToLoginOptions)
Redirect to account page
Redirects the user to the account page, where they can view/modify their user information.
authClient.redirectToAccountPage()
Or you can get the URL for the page with:
authClient.getAccountPageUrl()
Redirect to create org page
Redirects the user to the page where they can create organizations.
authClient.redirectToCreateOrgPage()
Or you can get the URL for the page with:
authClient.getCreateOrgPageUrl()
Redirect to org page
Redirects the user to an organization management page.
authClient.redirectToOrgPage(orgId?: string)
If orgId is specified, redirect to that organization’s page. If none is specified, a default is chosen deterministically.
Or you can get the URL for the page with:
authClient.getOrgPageUrl(orgId?: string)
Redirect to the setup SAML page
Redirects the user to a page where they can set up SAML for an organization.
authClient.redirectToSetupSAMLPage(orgId: string)
Or you can get the URL for the page with:
authClient.getSetupSAMLPageUrl(orgId: string)
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()