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 crossorigin 
        src="https://www.unpkg.com/@propelauth/javascript@1.2.0/dist/javascript.min.js"
        integrity="sha384-pMadYvjH0JNVI3hWTw5bcqu5qrOqBUXhcaTmBg4UjujHMuxd74zBO4ByZkZAQflR"></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, User, and Organization objects

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,
    // For all organizations the current user is a member of,
    //   this provides a mapping from their ids to metadata about them
    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;

  username?: string;
  firstName?: string;
  lastName?: string;
  pictureUrl?: string;

  locked: boolean;
  enabled: boolean;
  mfaEnabled: boolean;
}

// A mapping from an organizations id to metadata about them 
type OrgIdToOrgMemberInfo = {
  [orgId: string]: OrgMemberInfo
}

type OrgMemberInfo = {
    orgId: string,
    orgName: string,
    // The role of the user within this organization
    userRole: UserRole,
}

enum UserRole {
  Member = 0,
  Admin = 1,
  Owner = 2,
}

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

Redirect to login page

Redirects the user to the login hosted authentication page.

authClient.redirectToLoginPage()

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