Unqork Authentication API

openapi: 3.2.0
info:
  version: 1.0.0
  x-logo:
    url: https://developers.unqork.io/unqork-logo.png
    backgroundColor: '#FFFFFF'
  title: Unqork Customer Authentication API
  description: Unqork's customer REST API, based on open standards, allows you to set and retrieve module submission data, as well as control other aspects of your Unqork environment.
servers:
- url: https://{host}/api/1.0
  variables:
    host:
      default: env.unqork.io
      description: Environment host
security:
- OAuth2: []
tags:
- name: Authentication
paths:
  /referstring:
    post:
      x-unqork-service: true
      tags:
      - Authentication
      summary: Generates an encrypted referstring for authentication
      operationId: generateReferString
      description: '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

        ```

        ?refer=/#/display/

        ```

        - 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=/#/display/abcd123


        Examples


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


        Request


        ```

        {

        "userId": "user123",

        "expireOffset": 1,

        "expireMeasure": "days"

        }

        ```


        Response


        ```

        {

        "referString": ""

        }

        ```

        Example 2: Generate Refer String for single use (recommended)


        Request


        ```

        {

        "userId": "user123",

        "expireOffset": 1,

        "expireMeasure": "days",

        "oneTimeUse": true

        }

        ```


        Response


        ```

        {

        "referString": ""

        }

        ```


        Example 3: Generate Refer String for custom role


        Request

        ```

        {

        "userId": "user123",

        "expireOffset": 1,

        "expireMeasure": "days",

        "additionalParams": {

        "role": "customRole"

        }

        }

        ```


        Response

        ```

        {

        "referString": ""

        }

        ```


        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": ""

        }

        ```

        ### Authorization Required:

        - Designer Administrator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferStringRequest'
      responses:
        '200':
          description: Successful Generation
          content:
            application/json:
              schema:
                type: object
                required:
                - referString
                properties:
                  referString:
                    description: The encrypted refer string containing user information
                    type: string
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error
      required:
      - code
      - message
      properties:
        code:
          description: HTTP status code
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
    ReferStringRequest:
      type: object
      required:
      - userId
      properties:
        userId:
          type: string
          description: Unique ID of the user, as a string
        expireOffset:
          type: integer
          description: 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:
          type: string
          description: String with the units for the expireOffset parameter (e.g. hours, days). Maximum offset 30 days or equivalent. Default measure hours (Default offset is 1)
        oneTimeUse:
          type: boolean
          description: Whether to limit the refer string to one use. For best security, it is recommended to set `oneTimeUse` to `true`.
        additionalParams:
          type: object
          description: An object with anything else to be added to referstring
  securitySchemes:
    OAuth2:
      description: "The Unqork API implements the [OAuth 2.0 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) and the [OAuth 2.0 Password Grant](https://tools.ietf.org/html/rfc6749#section-1.3.3). Access via OAuth2 Client Credentials Grant can be utilized by creating Client Credentials through the API Access Management Administration page. Access via OAuth2 Password Grant can be enabled for all users in Environment Administration. Once OAuth2 Password Grant is enabled, all Unqork users can use their Unqork username/password to retrieve an access token.\n\nIn order to utilize any of the API resources, you must first retrieve an access token by POSTing your credentials to the access token URL, e.g. using `curl`:\n```\n  $ curl -u '{clientId}:{clientSecret}' -X POST --basic https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=client_credentials\"\n```\nOr:\n```\n  $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=password&username={username}&password={password}\"\n```\nThis returns an \"access_token\", which you would then retain and use in any subsequent resource requests. **Access tokens expire after one hour, at which point you must retrieve a new one.** The access token should be included in a request header:\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/api/1.0/{endpoint}\n```\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
        password:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A