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 without requiring them to log in manually—for example, in a notification email.

Important: Refer strings must always be generated server-side using a server-side executed (SSE) module. Never generate refer strings 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 (the portion of a URL after ?):

https://{environment}.unqork.io?refer={referString}/#/display/{resourceId}

Security Requirements

The /referstring API endpoint requires administrator privileges. This requirement 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:

1. A front-end module triggers an SSE module.

2. The SSE module determines the userId from the authenticated session server-side—the module does not accept userId as an input from the front end.

3. The SSE module calls /referstring with server-determined parameters.

4. The SSE module generates a URL with the refer string and sends it directly to the end-user—for example, by triggering a send email service. Never return 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.

Generating a Refer String

Refer strings are generated through the Unqork API. Call this endpoint from a server-side executed (SSE) module only.

Endpoint: POST /referstring

Request Parameters

Response

{
  "referString": "<encrypted refer string>"
}

Expiry

Refer strings expire based on the expireOffset and expireMeasure values set at generation time.

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 Practice: 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.

Common Use Cases

• Email notifications: Send end-users a direct link to a workflow submission or module using the Message node. Enable Generate and Send Refer String on the node to include a refer string automatically.

• One-time access links: Set oneTimeUse: true to generate a link that works only once—for example, a password reset or form completion link.

• Custom role assignment: Use additionalParams to assign a custom role to the authenticated session, controlling what the end-user can access. Set these values server-side only.

See Also

• Message Node — configure the node to generate and send refer strings automatically in a workflow.