---
title: "Generates an encrypted referstring for authentication"
method: POST
path: "/referstring"
tags: ["Authentication"]
---

# Generates an encrypted referstring for authentication

`POST /referstring`

This endpoint will generate encrypted refer strings that can be used to authenticate users into an Unqork environment

 Environment Variables - The following Environment Variables are required
 - key : key for encryption
 - cipher : method of encryption. The default and recommended cipher is aes-256-gcm.

 Include this refer string in the link to an Unqork resource as follows
   ```
   <hostname>?refer=<referString>/#/display/<resource_id>
   ```
   - hostname - host name of Unqork server
   - referString - referString returned from API
   - resource_id - Id of the Unqork resource to viewFor example, https://client.unqork.io?refer=<referString>/#/display/abcd123

 Examples

   Example 1: Generate Refer String for 1 day (default role)

   Request

   ```
    {
      "userId": "user123",
      "expireOffset": 1,
      "expireMeasure": "days"
    }
   ```

   Response

   ```
    {
      "referString": "<encrypted refer string>"
    }
   ```
   Example 2: Generate Refer String for single use (recommended)

   Request

   ```
    {
      "userId": "user123",
      "expireOffset": 1,
      "expireMeasure": "days",
      "oneTimeUse": true
    }
   ```

   Response

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

   Example 3: Generate Refer String for custom role

   Request
  ```
    {
      "userId": "user123",
      "expireOffset": 1,
      "expireMeasure": "days",
      "additionalParams": {
        "role": "customRole"
      }
    }
  ```

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

   Example 4: Generate Refer String with custom user parameters

   Request
  ```
    {
      "userId": "user123",
      "expireOffset": 1,
      "expireMeasure": "days",
      "additionalParams": {
        "custom1": "custom value 1",
        "custom1": "custom value 2",
        "custom1": "custom value 3"
      }
    }
  ```

   Response
  ```
    {
      "referString": "<encrypted refer string>"
    }
  ```
### Authorization Required:
  - Designer Administrator

## Request body

- ReferStringRequest
  - `userId` string, required — Unique ID of the user, as a string
  - `expireOffset` integer — Provides an amount of time until expiry, used in conjunction with the units from expireMeasure. Maximum offset 30 days or equivalent. Default offset 1 (default unit is hours).
  - `expireMeasure` string — String with the units for the expireOffset parameter (e.g. hours, days). Maximum offset 8 days or equivalent. Default measure hours (Default offset is 1)
  - `oneTimeUse` boolean — Whether to limit the refer string to one use. For best security, it is recommended to set `oneTimeUse` to `true`.
  - `additionalParams` object — An object with anything else to be added to referstring

## Response `200`

Successful Generation

- object
  - `referString` string, required — The encrypted refer string containing user information

## Other responses

- `default` — Error

---

[API](https://skmtc.net/unqork/apis/unqork-customer-api.md) · [All operations](https://skmtc.net/unqork/apis/unqork-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unqork/unqork-customer-api/revisions/112399a67ebb/schema)