---
title: "Refer Strings"
slug: "refer-strings"
updated: 2026-09-14T17:38:03Z
published: 2026-09-14T17:38:03Z
canonical: "docs.unqork.io/refer-strings"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Refer Strings

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

> [!WARNING]
> 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](/docs/refer-strings#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 `?`):

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

| Placeholder | Description |
| --- | --- |
| `{environment}` | Your Unqork environment subdomain (for example, `client`). |
| `{referString}` | The encrypted refer string returned by the API. |
| `{resourceId}` | The ID of the Unqork resource the end-user should land on. |

## 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

| 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. |
| `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. |

### Response

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

## Expiry

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

| 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 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](/unqorkai/docs/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.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-06-03 | Added Security Requirements section; clarified SSE-only generation; updated userId and additionalParams descriptions to reflect server-side determination. |
| — | Initial publication. |

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

Server-Side Execute (SSE) means data is executed outside of the end-users browser. This increases security by preventing data from being manpulated by bad actors.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE.

The Number data type accepts integer or floating point values. The number data type does not use quotes around numerical values.

The Boolean data type accepts one of two values: true, or, false.

An encrypted token generated by the Unqork API that authenticates an end-user into an Express application through a URL. Refer strings are commonly used in notification emails to give end-users a direct link to a module without requiring them to log in manually.