Unqork Users 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 Users 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: Users
  description: The following endpoints are available to "Administrator" users only.
paths:
  /users:
    get:
      tags:
      - Users
      summary: Get Users
      operationId: getUsers
      description: 'Returns Express user objects. This is a paged endpoint (see Paging).

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: limit
        in: query
        description: Maximum number of results to return (default 50, maximum 500)
        required: false
        schema:
          type: integer
          format: int32
          default: 50
          maximum: 500
      - name: sort
        in: query
        description: Field to sort by. Use [field name] for ascending and -[field name] for descending order. You can `,` seperate for multiple sort orders.
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: "Filter conditions for searching users, formatted like `?filter=name=Bill`. The filters should be `;` separated, as shown below. Supported fields are \"role\", \"name\", \"phone\", \"email\", \"userId\", \"groups\", \"applicationRoles\". All filter conditions are \"starts with\". NOTE: When filtering on `created` and `modified`, all timestamps are in UTC. You need to encode reserved url characters if they are part of the data you are filtering.  Example, * ' ( ) : @ & = + $ , / ? % # [ ] You need to double encode `;` as `%253B` if it is a part of the data you are filtering.\n\nExamples:\n  - `filter=email=john@doe.com` will fetch all users starting with email \"john@doe.com\"\n  - `filter=filter={\"name\":{\"$eq\":\"john@doe.com\"}}` will fetch all users that exactly match \"john@doe.com\"\n  - `filter=role=Admin;created>2019-06-11T21:50:57.067Z` will fetch all user with role starting with \"Admin\" and created after \"2019-06-11T21:50:57.067Z\" (UTC)\n  - `filter=modified=2019-06-11T21:50:57.067Z` will fetch users modified at exactly \"2019-06-11T21:50:57.067Z\" (UTC)\n  - `filter=created>2019-06-11T00:00:00.000Z;created<2019-06-20T00:00:00.000Z` will fetch users created between \"2019-06-11T00:00:00.000Z\" (UTC) and \"2019-06-20T00:00:00.000Z\" (UTC)\n\n\nSupported operators (as specified in this library [api-query-params](https://github.com/loris/api-query-params)):\n  - key=val  `type=public`\n  - key>val  `count>5`\n  - key>=val  `rating>=9.5`\n  - key<val  `createdAt<2016-01-01`\n  - key<=val  `score<=-5`\n  - key!=val  `status!=success`\n  - key=val1,val2  `country=GB,US`\n  - key!=val1,val2  `lang!=fr,en`\n  - key  `phone`\n  - !key  `!email`\n  - key=/value/<opts>  `email=/@gmail\\.com$/i`\n  - key!=/value/<opts> `phone!=/^06/`\n\nNote: multiple forward slashes (/) are interpreted as a regex. To use a string comparison wrap your parameter with string(). Ex. email=string(/@gmail\\.com$/i).\n"
        schema:
          type: string
      - name: showServiceUsers
        in: query
        description: "Whether to allow show all users or all non service users. Note - The value should be passed as true/false\nExamples:\n  - `showServiceUsers=true` will show all the users in the system\n  - `showServiceUsers=false` will show all the non service users\n  - If the argument is not passed, by default all non service users will be displayed.\n"
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Users
      summary: Create User
      operationId: createUser
      description: 'Creates a new user. If userId is not specified, it is auto-generated and returned.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: shouldNotify
        in: query
        description: Whether to notify the user via email of their temporary password.
        schema:
          type: boolean
      - name: skipTemporaryPassword
        in: query
        description: Whether to set the user's password as permanent immediately. A password must be provided in the body if this flag is set. This flag cannot be used if "shouldNotify" is also set.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPost'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}:
    get:
      tags:
      - Users
      summary: Get User
      operationId: getUser
      description: 'Returns an Express user object based on a user ID.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: userId
        in: path
        description: ID of user to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Users
      summary: Update User
      operationId: updateUser
      description: 'Updates a single user. Partial updates are supported. To delete a specific custom attribute, pass null for that attribute.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: userId
        in: path
        description: ID of user to update
        required: true
        schema:
          type: string
      - name: shouldNotify
        in: query
        description: 'Controls the distribution of the **New Account (Token Invitation)** email.


          * `true`: Sends both the "New Account" email and the "User Changed" email.

          * `false`: Suppresses the "New Account" email only. The "User Changed" email is still sent to the user.


          Note: This parameter acts specifically on the Token Invitation workflow and does not globally suppress all system notifications.'
        schema:
          type: boolean
          default: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPut'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Users
      summary: Delete User
      operationId: deleteUser
      description: 'Deletes a user based on the user ID supplied. Note that users are hard-deleted, and this is not reversible. If a user is a system user, it cannot be deleted.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: userId
        in: path
        description: ID of user to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User deleted
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/passwordStatus:
    get:
      tags:
      - Users
      summary: Get User Password Status
      operationId: getUserPasswordStatus
      description: 'Returns the user''s password status based on a user ID.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: userId
        in: path
        description: ID of user to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User Password Status
          content:
            application/json:
              schema:
                type: object
                required:
                - userId
                - passwordStatus
                properties:
                  userId:
                    type: string
                  passwordStatus:
                    type: string
                    description: 'Status of the user''s password:

                      * `TEMPORARY` - User must change password at first login. If temporary password has expired, a new one must be resent using PUT.

                      * `OK` - User has already changed their temporary password.

                      * `FORCED_RESET` - User has to reset their password.

                      * `N/A` - Not applicable

                      '
                    enum:
                    - OK
                    - TEMPORARY
                    - N/A
        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
    UserResponse:
      type: object
      required:
      - userId
      - name
      - email
      - created
      - modified
      properties:
        userId:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        role:
          type: string
          description: One of the roles configured in Unqork
          default: Authenticated
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
          default:
          - Authenticated
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork
          default: []
        applicationRoles:
          type: object
          description: Map of applications to roles
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        isServiceUser:
          type: boolean
          format: true/false
        lastLogin:
          type: string
          format: date-time
        '...customAttributes':
          type: string
          description: Custom attributes will be included as additional keys in the response body.
    UserPut:
      type: object
      properties:
        userId:
          type: string
          description: 'The unique identifier of the user account. The userId can only include letters, numbers, and the following characters @,+-_.


            **Immutable**: This value cannot be modified. If provided in the request body, it must match the `userId` in the path, or it will be ignored.'
        name:
          type: string
          description: The name can only include letters, numbers, and the following characters @,+-_.'
        email:
          type: string
          maxLength: 254
          format: email
          description: Quotes and special characters `"(),:;<>@[]\` are not allowed. The local portion of the email (e.g. local@domain.com) must be > 0 characters and < 64 charaters. There cannot be consecutive dots (e.g. `..`) in the email
        phone:
          type: string
          description: Must be a valid US phone number unless the country code is specified, in which case it is validated with [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js#definitions)
        role:
          type: string
          description: One of the roles configured in Unqork
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork OR comma-separated list of groups configured in Unqork (e.g. "group1,group2")
        applicationRoles:
          type: object
          description: Map of applications to roles OR comma-separated list of application-role mappings (e.g. "application1:role1,application2:role2")
        password:
          type: string
          format: password
        isServiceUser:
          type: boolean
          format: true/false
        '...customAttributes':
          type: string
          description: Custom attributes can be included as additional keys in the request body. Only string values of custom attributes are supported.
    UserPost:
      type: object
      required:
      - name
      - email
      properties:
        userId:
          type: string
          description: The userId can only include letters, numbers, and the following characters @,+-_.
        name:
          type: string
          description: The name can only include letters, numbers, and the following characters @,+-_.'
        email:
          type: string
          maxLength: 254
          format: email
          description: Quotes and special characters `"(),:;<>@[]\` are not allowed. The local portion of the email (e.g. local@domain.com) must be > 0 characters and < 64 charaters. There cannot be consecutive dots (e.g. `..`) in the email
        phone:
          type: string
          description: Must be a valid US phone number unless the country code is specified, in which case it is validated with [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js#definitions)
        role:
          type: string
          description: One of the roles configured in Unqork
          default: Authenticated
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
          default:
          - Authenticated
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork OR comma-separated list of groups configured in Unqork (e.g. "group1,group2")
          default: []
        applicationRoles:
          type: object
          description: Map of applications to roles OR comma-separated list of application-role mappings (e.g. "application1:role1,application2:role2")
        password:
          type: string
          format: password
        isServiceUser:
          type: boolean
          format: true/false
        '...customAttributes':
          type: string
          description: Custom attributes can be included as additional keys in the request body. Only string values of custom attributes are supported.
  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