Refer Strings

A refer string is an encrypted token that authenticates an end-user into an Unqork environment through a URL. Use refer strings when you need to send end-users a direct link to a module—for example, in a notification email—without requiring them to log in manually.

Important: Refer strings must always be generated server-side using a server-side executed (SSE) module. Never generate them in a front-end module. See Security Requirements below.

How Refer Strings Work

When an end-user follows a refer string link, Unqork validates the token and logs the end-user in. The end-user lands directly on the specified resource without seeing a login screen.

The refer string is appended to the resource URL as a query parameter:

<hostname>?refer=<referString>/#/display/<moduleID>

Security Requirements

The /referstring API endpoint requires administrator privileges. This has important security implications.

Never generate refer strings in a front-end module. Calling /referstring directly from the front end either fails for regular Express users—who lack the required permissions—or, if the module runs with elevated access, creates a serious vulnerability: anyone who can intercept or modify the API request could pass in arbitrary userId, role, or additionalParams values and the server would honor them.

The correct pattern is:

A front-end module triggers an SSE module.
The SSE module determines the userId from the authenticated session server-side—it does not accept userId as an input from the front end.
The SSE module calls /referstring with server-determined parameters.
The SSE module returns the encrypted token to the front end.

Never pass userId, role, or other sensitive parameters from the front end into the SSE module as inputs. These values must be determined entirely server-side.

API Reference

Call this endpoint from a server-side executed (SSE) module only.

Endpoint: POST /referstring

Request Parameters

Parameter	Type	Required	Description
`userId`	String	Yes	The ID of the end-user to authenticate. Must be determined server-side—never passed in from the front end.
`additionalParams`	Object	No	Custom key-value pairs added to the end-user's session when they authenticate. Set these values server-side only. The resulting token must be less than 4,096 characters.
`expireMeasure`	String	No	The unit for `expireOffset`. Options include: `minutes`, `hours`, `days`, `weeks`. Default: `hours`.
`expireOffset`	Number	No	How long until the refer string expires. Default: `1`. Maximum: 30 days.
`oneTimeUse`	Boolean	No	When set to `true`, the refer string becomes invalid after its first use.

Expiry

Limit	Value
Default expiry	1 hour
Maximum expiry	30 days

Once a refer string expires, the link no longer authenticates the end-user. Generate a new refer string if you need to resend the link.

Best Practices

Always generate refer strings in an SSE module, never in a front-end module.
Set the shortest expiry that fits your use case. Avoid defaulting to the maximum—long-lived refer strings increase security exposure if a link is forwarded or intercepted.
Set oneTimeUse: true whenever the link should only be followed once, for example for password resets or one-time form submissions.
Never accept userId, role, or other authentication parameters as inputs from the front end.

Documentation Index