sitemap.xml llms.txt
Skip to main content

User Functions

To manage users, use the functions exported by the User adapter.

Importing the adapter​

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

The userAdapter namespace exports functions that make calls to the User API.

learn more

For descriptions of the objects used by the User adapter functions, read User entities.

Create​

Create user​

The createUser() function creates a new user.

The user can be either a native user or an external user.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /user endpoint.
  • Creates either a native user or an external user based on the view parameter.
  • Accepts user profile fields such as handle, displayName, email, and authentication details.
  • Returns the newly created PseudonymReadOutView object.
Function signature
export async function createUser<R extends object = RealmData>(
    view: NativeUserCreateInView | ExternalUserCreateInView,
    optionals: RoutingOptions = {},
): Promise<PseudonymReadOutView>

Parameters​

Return value​

Returns a promise that resolves to a PseudonymReadOutView object representing the created user.

Usage example​

import { userAdapter } from 'epicenter-libs';

// Create a native user
const user = await userAdapter.createUser({
    objectType: 'native',
    handle: 'john.doe',
    displayName: 'John Doe',
    email: 'john@example.com',
});

Upload users via CSV​

The uploadCSV() function uploads a CSV file to create or update multiple users.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /user/upload endpoint.
  • Uploads a CSV file containing user data using FormData.
  • Supports an optional overwrite flag to update existing users.
  • Returns a report summarizing created, updated, and discarded users.
Function signature
export async function uploadCSV(
    file: File,
    optionals: UploadOptions = {},
): Promise<UserReport>

Parameters​

  • file (File) – CSV file containing user data
  • optionals (UploadOptions):
    • overwrite? (boolean) – If true, overwrites existing users with matching identifiers; defaults to false
    • RoutingOptions – Additional routing options

Return value​

Returns a promise that resolves to a UserReport object containing details about created, updated, and discarded users.

Usage example​

import { userAdapter } from 'epicenter-libs';

const file = new File([csvContent], 'users.csv');

const report = await userAdapter.uploadCSV(file, {
    overwrite: true,
});

Retrieve​

Get user by key​

Gets a specific user by user key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /user/{USER_KEY} endpoint.
  • Retrieves a PseudonymReadOutView object associated with the specified user key.
Function signature
export async function get(
    userKey: string,
    optionals: RoutingOptions = {},
): Promise<PseudonymReadOutView>

Parameters​

  • userKey (string): The unique key identifying the user.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

Returns a promise that resolves to a PseudonymReadOutView object representing the requested user.

Usage example​

import { userAdapter } from 'epicenter-libs';

const user = await epicenter.userAdapter.get('00000179b4d3fb0c84f822df8cd2aa36ke96');

Get user by handle​

Gets a specific user by user handle.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The getWithHandle() function:

  • Retrieves a user based on their unique handle and specified modality (if any).
  • Constructs a GET request to:
    • /user/with/{HANDLE} when no modality is provided
    • /user/with/{HANDLE}/{MODALITY} when a modality is specified
  • Retrieves the PseudonymReadOutView object associated with the specified handle.
Function signature
export async function getWithHandle(
    handle: string,
    optionals: {
        modality?: Modality;
    } & RoutingOptions = {},
): Promise<PseudonymReadOutView>

Parameters​

  • handle (string): The user's handle.
  • optionals (Type: { modality?: Modality } & RoutingOptions = {}):

Return value​

Returns a promise that resolves to a PseudonymReadOutView object representing the requested user.

Usage example​

import { userAdapter } from 'epicenter-libs';

userAdapter.getWithHandle('user@server.com', { modality: 'SSO' });