Proxies

An Epicenter proxy is a server-side component that sits between your participants' browsers and the Epicenter API. Rather than having the browser call Epicenter directly, requests travel through the proxy first. This indirection serves two purposes: it can add elevated credentials that the browser does not possess, and it can filter what data is exposed so that only designated public information is served to participants.

How proxies work

Every Epicenter API request is routed through the Router class in epicenter-libs. By default, the router targets the Epicenter API directly:

https://epicenter.forio.com/api/v3/{account}/{project}/{endpoint}

When proxy routing is enabled, the router prepends a proxy path component:

https://epicenter.forio.com/proxy/{account}/{project}/api/v3/{account}/{project}/{endpoint}

Epicenter intercepts requests at the proxy/{account}/{project}/ prefix and forwards them to the proxy. To handle those requests, you must implement the necessary logic in the proxy.

To learn more about implementing and using a proxy, read this guide.

When a proxy is the right tool

In Epicenter, a proxy serves as a permission elevation mechanism. It is best to limit the proxy functionality to the minimum required by the application.

• Elevated privileges: Certain Epicenter operations require a role higher than FACILITATOR. If your application needs participants to trigger these operations, a proxy lets you do so safely. For a full discussion of elevated privileges, see Privileged Functions.
• Long-running requests: A request can kick off work on the server that continues running after the participant closes their browser.

Important

Note, that it is not dependable to store state in the proxy.

warning

Using a proxy, you run a the risk of potentially weakening the security of your application. It is your responsibility to authenticate the users of the application that makes requests to a proxy.

Use-case example

In multi-team simulations, participants often need to read data from other teams' worlds. However, each world may also contain private data that should never be visible to other teams. A proxy can provide a dedicated endpoint that returns only the variables explicitly designated as public in that world.

Learn moe

For details, please see the Proxy tutorial.

Implementing a proxy

To create a proxy file (typically named index.js) for your project:

1. Start by copying the \proxy\index.js file from the proxy branch of dev-base-build. The example implements some boilerplate proxy functionality.
2. Once you clone the example index.js, add your request handlers to the file.

Read credentials from the environment

Important

For use-cases that require elevated permissions, the proxy should read the API secret key from the environment context.

Here is a code snippet from the Proxy developer tutorial that demonstrates reading the proxy configuration from the environment and setting its context dynamically.

const proxyConfig = epicenter.proxyConfig();
config.setContext({
  apiProtocol: proxyConfig.apiScheme.toLowerCase(),
  apiHost: proxyConfig.apiHost,
  accountShortName: proxyConfig.accountShortName,
  projectShortName: proxyConfig.projectShortName,
});

Learn more

For a hands-on example of a project with a proxy, follow the Proxy developer tutorial.

Enabling proxy routing

A proxy can only be used with team projects.

note

Using a proxy requires an eligible plan or an account specifically enabled by Forio. If proxies are not enabled for your account, contact a Forio representative at support@forio.com.

Secret key

Before using a proxy, create a secret key for your organization.

Project settings

To enable a proxy for a team project, configure it in the project settings.

Per-request routing

To enable proxy routing for individual adapter calls, pass useProjectProxy: true in the RoutingOptions parameter of the adapter function:

import { worldAdapter } from 'epicenter-libs';

const result = await worldAdapter.get(
    episodeKey,
    worldKey,
    { useProjectProxy: true },
);

Tasks and the proxy

When you schedule a task that issues an HTTP request, you can direct that request through the project proxy by setting target to 'PROXY' in the task payload:

{
    method: 'POST',
    url: '/api/v3/{account}/{project}/world/{episodeKey}/{worldKey}',
    body: { roundComplete: true },
    target: 'PROXY',
}

With target: 'PROXY', Epicenter routes the task's outbound HTTP call through the proxy, attaching the project secret key before forwarding to the API. The alternative value, 'APPLICATION', routes the call to your project's application server instead.

Local development

When epicenter-libs detects a local origin (a URL that resolves to localhost or an ngrok host), proxy routing behaves differently:

• The proxy() utility fetches the resource path directly, without prepending the /proxy/{account}/{project}/ prefix.
• Adapter calls with useProjectProxy: true still build the proxy-style URL, but the request goes to your local development server rather than the Epicenter proxy.

This means you can develop and test proxy-aware code locally without needing the Epicenter proxy infrastructure running.