---
title: "Refer Strings"
slug: "refer-strings"
description: "Learn how to use refer strings in Unqork for secure user authentication and access without an account, enhancing your application's usability."
updated: 2026-06-12T19:01:01Z
published: 2026-06-12T19:01:01Z
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 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](/v1/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 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](/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.

---

## See Also

- [Message Node](/v1/docs/message-node) — configure the node to generate and send refer strings automatically in a workflow.

---

**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 string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

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

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

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.

Front-End (FE) Modules act as the user interface (UI) that end-users see and interact with. FE Modules use Plug-Ins to securly connect to API Modules for executing API calls.

A query lets you retrieve, access, manipulate, and delete data in a database.

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.

An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.

An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

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.

Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections.