Privileged Functions
Some functions in the JS libraries require a role higher than FACILITATOR. For example, a role of SUPPORT, AUTHOR, or OWNER. This guide explains why a user session can never reach those roles, and how your application should call such functions instead.
Calling privileged functions
The FACILITATOR ceiling
A user session is scoped to a single group, and its permissions come entirely from the user's groupRole. The highest group role is FACILITATOR.
There is no function in the JS libraries that lets a logged-in user, or an application acting on a user's behalf, grant themselves or anyone else a role above FACILITATOR. For example:
groupAdapter.addUser()andgroupAdapter.updateUser()only accept the group roles:FACILITATOR,REVIEWER,LEADER, andPARTICIPANT.userAdapter.createUser()creates a user record with no role at all. Roles are assigned with group membership.
Roles above FACILITATOR (such as SUPPORT, AUTHOR, OWNER, SYSTEM) are account-level, not group-level, and Epicenter does not allow a user session to escalate into account-level territory.
For every adapter function, the reference documentation specifies the required role. For example, the accountAdapter.createAccount() function requires a SYSTEM role.
Use application credentials
Functions that require SUPPORT or higher are meant to be called with application credentials (i.e., the project's secret key) rather than with a user's handle and password.
Logging in with a secret key produces an admin session that Epicenter treats as equivalent to an AUTHOR role for your account. Because AUTHOR outranks both SUPPORT and ASSOCIATE in the role hierarchy, this session satisfies any function that requires SUPPORT, ASSOCIATE, or AUTHOR. It does not, however, satisfy functions that require OWNER which is reserved for an actual account owner.
import { authAdapter } from 'epicenter-libs';
const session = await authAdapter.login({ secretKey: process.env.EPICENTER_SECRET_KEY });
For the full list of properties, read AppCredentials in the Authentication adapter reference.
Keep the secret key server-side
The secret key grants access to all data across every group in your project, so it must never be shipped to the browser or embedded in client-side code. Treat it the same as you would a database password.
In practice, this means functions that require SUPPORT or higher should be called from a trusted server that your application controls (such as a backend service, a build or CI step, or a server-side model) and never directly from code that runs in a user's browser. If your front end needs the result of one of these calls, have it request the result from your own server, which holds the secret key and makes the privileged call on the front end's behalf.
Where a project needs elevated privileges from within a client request, Epicenter supports a proxy pattern where your own backend sits between your front end and Epicenter, forwarding requests and adding the secret key where needed.
See the UseProjectProxy type on the Router utility.
Where the secret key comes from
An application's secret key is set up by an Epicenter account owner, not by application code. An account owner sets or rotates the shared secret from the account settings in the Epicenter UI. From there, it should be stored as a secret in your server's environment (for example, as an environment variable), not checked into source control.
For background on account roles, read Create secret key.