sitemap.xml llms.txt
Skip to main content

Registration Functions

To manage user registration in your Epicenter application, leverage the Registration adapter.

Importing the adapter​

To use the functions of the Registration adapter, import it as shown:
import { registrationAdapter } from 'epicenter-libs';

The registrationAdapter namespace exports functions that make calls to the Registration API.

learn more

For descriptions of the objects used by the registration adapter functions, read Registration Entities.

Self-registration​

Use these functions to implement functionality to enable prospective users to join a user group in your Epicenter application.

Important

Self-registration needs to be turned on in the workshop settings in Epicenter.

Send self-registration invite​

Send a self-registration invite email that allows a user to create their own account.

localization

Pass an Accept-Language header via optionals.headers to localize the invite email.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The sendSelfRegistrationInvite() function:

  • Constructs a POST request to /registration/self/{groupKey}.
  • Sends the recipient's email address and optional configuration in the request body.
  • Returns a promise that resolves to void when the invite is dispatched successfully.
Function signature
export async function sendSelfRegistrationInvite(
    groupKey: string,
    email: string,
    optionals: {
        linkDestination?: 'DASHBOARD' | 'MANAGER';
        modality?: 'NONE' | 'HBP' | 'ICC' | 'SSO';
        redirectUrl?: string;
        subject?: string;
        givenName?: string;
        familyName?: string;
        linkUrl?: string;
        confirmation?: boolean;
    } & RoutingOptions = {},
): Promise<void>

Parameters​

  • groupKey (type: string): Unique GUID of the group to add the user to.
  • email (type: string): Email address of the user to invite.
  • optionals (optional, type: object): Invite configuration and routing options.
    • linkDestination ('DASHBOARD' | 'MANAGER'): Specifies the platform. Use 'DASHBOARD'. 'MANAGER' is legacy and is persisted for backward compatibility. 'MANAGER' is the default value.
    • modality ('NONE' | 'HBP' | 'ICC' | 'SSO'): Modality specifies the type of SSO. If 'NONE', the user will log in using their handle and password.
    • redirectUrl (string): URL to redirect to after the user completes registration.
    • subject (string): Subject line for the invite email.
    • givenName (string): The prospective user's given name.
    • familyName (string): The prospective user's family name.
    • linkUrl (string): Use this parameter to overwrite the default self-registration URL from the workshop settings.
    • confirmation (boolean): Whether to send a confirmation email after registration.
    • RoutingOptions (object): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to void.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
await registrationAdapter.sendSelfRegistrationInvite('group-key', 'user@example.com', {
    linkDestination: 'DASHBOARD',
    redirectUrl: 'https://app.example.com',
    headers: { 'Accept-Language': 'fr-FR' },
});

Get self-registration info​

Retrieve contextual information stored in a self-registration token before completing registration.

Permissions​

Requires a role of SYSTEM or higher.

Function description​

The getSelfRegistrationInfo() function:

  • Constructs a GET request to /registration/self/{token}.
  • Returns a RegistrationInfo object containing details such as the group, project, account, and any pre-populated user fields associated with the token.
Function signature
export async function getSelfRegistrationInfo(
    token: string,
    optionals: RoutingOptions = {},
): Promise<RegistrationInfo>

Parameters​

  • token (type: string): The self-registration token.
  • optionals (optional, type: RoutingOptions): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to a RegistrationInfo.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const info = await registrationAdapter.getSelfRegistrationInfo('my-token');

Complete self-registration​

Finalize a user's account by redeeming a self-registration token.

Function description​

The completeSelfRegistration() function:

  • Constructs a PATCH request to /registration/self/{token}.
  • Sends the user's chosen password and any optional profile fields in the request body.
  • Returns a RegistrationResult containing the new session and an optional redirect URL.
Function signature
export async function completeSelfRegistration(
    token: string,
    password: string,
    optionals: {
        displayName?: string;
        givenName?: string;
        familyName?: string;
        handle?: string;
    } & RoutingOptions = {},
): Promise<RegistrationResult>

Parameters​

  • token (type: string): The self-registration token.
  • password (type: string): Password for the new user account.
  • optionals (optional, type: object): Profile fields and routing options.
    • displayName (string): Display name for the new user.
    • givenName (string): Given name for the new user.
    • familyName (string): Family name for the new user.
    • handle (string): Handle for the new user.
    • RoutingOptions (object): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to a RegistrationResult.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const result = await registrationAdapter.completeSelfRegistration('my-token', 'secret123', {
    displayName: 'John Doe',
    handle: 'johnd',
});

Registration invites​

Send invite​

Send a facilitator-issued invite email to add a specific user to a group.

localization

Pass an Accept-Language header via optionals.headers to localize the invite email.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The sendInvite() function:

  • Constructs a POST request to /registration/invite/{groupKey}.
  • Sends the recipient's email address and optional configuration in the request body.
  • Returns a promise that resolves to void when the invite is dispatched successfully.
Function signature
export async function sendInvite(
    groupKey: string,
    email: string,
    optionals: {
        linkDestination?: 'DASHBOARD' | 'MANAGER';
        modality?: 'NONE' | 'HBP' | 'ICC' | 'SSO';
        redirectUrl?: string;
        subject?: string;
        givenName?: string;
        familyName?: string;
        linkUrl?: string;
        confirmation?: boolean;
    } & RoutingOptions = {},
): Promise<void>

Parameters​

  • groupKey (type: string): Unique GUID of the group to invite the user into.
  • email (type: string): Email address of the user to invite.
  • optionals (optional, type: object): Invite configuration and routing options.
    • linkDestination ('DASHBOARD' | 'MANAGER'): Specifies the platform. Use 'DASHBOARD'. 'MANAGER' is legacy and is persisted for backward compatibility. 'MANAGER' is the default value.
    • modality ('NONE' | 'HBP' | 'ICC' | 'SSO'): Modality specifies the type of SSO. If 'NONE', the user will log in using their handle and password.
    • redirectUrl (string): URL to redirect to after the user completes registration.
    • subject (string): Subject line for the invite email.
    • givenName (string): The prospective user's given name. The value gets pre-populated in the registration form.
    • familyName (string): The prospective user's family name. The value gets pre-populated in the registration form.
    • linkUrl (string): The registration link.
    • confirmation (boolean): Whether to send a confirmation email after registration.
    • RoutingOptions (object): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to void.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
await registrationAdapter.sendInvite('group-key', 'invited@example.com', {
    givenName: 'New',
    familyName: 'User',
    linkDestination: 'DASHBOARD',
    redirectUrl: 'https://app.example.com',
});

Get registration info​

Retrieve contextual information stored in an invite token before completing registration.

Permissions​

Requires a role of SYSTEM or higher.

Function description​

The getInviteRegistrationInfo() function:

  • Constructs a GET request to /registration/invite/{token}.
  • Returns a RegistrationInfo object containing details associated with the invite token.
Function signature
export async function getInviteRegistrationInfo(
    token: string,
    optionals: RoutingOptions = {},
): Promise<RegistrationInfo>

Parameters​

  • token (type: string): The invite registration token.
  • optionals (optional, type: RoutingOptions): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to a RegistrationInfo.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const info = await registrationAdapter.getInviteRegistrationInfo('invite-token');

Send team invite​

Send an invite email to add a user to a team account with a specified role.

note

To localize the invite email, pass an Accept-Language header via optionals.headers (part of RoutingOptions).

Permissions​

Requires a role of AUTHOR or higher.

Function description​

The sendTeamInvite() function:

  • Constructs a POST request to /registration/team.
  • Sends the inviting author's identifier, the role to assign, a redirect URL, the recipient's email address, and any optional fields in the request body.
  • Returns a promise that resolves to void when the invite is dispatched successfully.
Function signature
export async function sendTeamInvite(
    invitingAuthor: string,
    role: TeamRole,
    redirectUrl: string,
    email: string,
    optionals: {
        subject?: string;
        givenName?: string;
        familyName?: string;
    } & RoutingOptions = {},
): Promise<void>

Parameters​

  • invitingAuthor (type: string): Name or identifier of the person sending the invite.
  • role (type: TeamRole): Role to assign to the invited user.
  • redirectUrl (type: string): URL to redirect to after the user accepts the invite.
  • email (type: string): Email address of the user to invite.
  • optionals (optional, type: object): Additional invite fields and routing options.
    • subject (string): Subject line for the invite email.
    • givenName (string): Pre-populates the given name for the invited user. The value gets pre-populated in the registration form.
    • familyName (string): Pre-populates the family name for the invited user. The value gets pre-populated in the registration form.
    • RoutingOptions (object): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to void.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
await registrationAdapter.sendTeamInvite(
    'Jane Author',
    'AUTHOR',
    'https://app.example.com',
    'newteammate@example.com',
    { subject: 'Welcome to the team!' },
);

Get team registration info​

Retrieve contextual information stored in a team invite token before completing team registration.

Permissions​

Requires a role of SYSTEM or higher.

Function description​

The getTeamRegistrationInfo() function:

  • Constructs a GET request to /registration/team/{token}.
  • Returns a TeamRegistrationInfo object containing details associated with the team invite token.
Function signature
export async function getTeamRegistrationInfo(
    token: string,
    optionals: RoutingOptions = {},
): Promise<TeamRegistrationInfo>

Parameters​

  • token (type: string): The team invite token.
  • optionals (optional, type: RoutingOptions): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to a TeamRegistrationInfo.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const info = await registrationAdapter.getTeamRegistrationInfo('team-token');

Complete invite registration​

Finalize a user's account by redeeming a facilitator-issued invite token.

Function description​

The completeInviteRegistration() function:

  • Constructs a PATCH request to /registration/invite/{token}.
  • Sends the user's chosen password and any optional profile fields in the request body.
  • Returns a RegistrationResult containing the new session and an optional redirect URL.
Function signature
export async function completeInviteRegistration(
    token: string,
    password: string,
    optionals: {
        displayName?: string;
        givenName?: string;
        familyName?: string;
        handle?: string;
    } & RoutingOptions = {},
): Promise<RegistrationResult>

Parameters​

  • token (type: string): The invite registration token.
  • password (type: string): Password for the new user account.
  • optionals (optional, type: object): Profile fields and routing options.
    • displayName (string): Display name for the new user.
    • givenName (string): Given name for the new user.
    • familyName (string): Family name for the new user.
    • handle (string): Handle for the new user.
    • RoutingOptions (object): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to a RegistrationResult.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const result = await registrationAdapter.completeInviteRegistration('invite-token', 'pass456', {
    displayName: 'Jane Doe',
});

SSO​

Get SSO admin registration info​

Retrieve SSO registration data for an admin session using the specified SSO protocol.

Function description​

The getSsoAdminRegistration() function:

  • Constructs a GET request to /registration/sso/admin/{ssoProtocol}.
  • Returns the SSO registration payload for an admin-level session.
Function signature
export async function getSsoAdminRegistration(
    ssoProtocol: SsoProtocol,
    optionals: RoutingOptions = {},
): Promise<unknown>

Parameters​

  • ssoProtocol (type: SsoProtocol): The SSO protocol to use. Currently only 'SAML' is supported.
  • optionals (optional, type: RoutingOptions): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to the SSO admin registration data returned by the API.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const info = await registrationAdapter.getSsoAdminRegistration('SAML');

Get SSO user registration info​

Retrieve SSO registration data for a user session using the specified SSO protocol.

Function description​

The getSsoUserRegistration() function:

  • Constructs a GET request to /registration/sso/user/{ssoProtocol}.
  • Returns the SSO registration payload for a user-level session.
Function signature
export async function getSsoUserRegistration(
    ssoProtocol: SsoProtocol,
    optionals: RoutingOptions = {},
): Promise<unknown>

Parameters​

  • ssoProtocol (type: SsoProtocol): The SSO protocol to use. Currently only 'SAML' is supported.
  • optionals (optional, type: RoutingOptions): An optional parameter providing additional routing options. Defaults to an empty object.

Return value​

A promise that resolves to the SSO user registration data returned by the API.

Usage example​
import { registrationAdapter } from 'epicenter-libs';
const info = await registrationAdapter.getSsoUserRegistration('SAML');