Unqork Credentials 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 Credentials 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: Credentials
paths:
  /credentials:
    get:
      tags:
      - Credentials
      summary: Get credentials
      operationId: credentialsGetAll
      description: 'Get credentials.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 100000
        description: 'Integer to limit the number of applications returned (Cannot exceed 1000)

          '
      - name: sort
        in: query
        schema:
          type: string
          default: created
        description: 'Field to sort found applications by

          '
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: 'Offset for paginated results

          '
      - name: sortOrder
        in: query
        schema:
          type: integer
          default: -1
        description: 'Sort order for found applications (1 = ascending, -1 = descending)

          '
      - name: filter
        in: query
        schema:
          type: string
        description: "Filter conditions for searching users, formatted like `?filter=name=Bill`. The filters should be `;` separated, as shown below. Supported fields are \"credentialType\", \"name\". 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=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"
      responses:
        '200':
          description: Array containing JSON objects of each found credential
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CredentialResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Credentials
      summary: Create credential
      operationId: credentialsCreate
      description: 'Create a credential.

        ### Authorization Required:

        - Designer Administrator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialRequest'
      responses:
        '200':
          description: JSON describing the created credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{clientId}:
    put:
      tags:
      - Credentials
      summary: Update credential
      operationId: credentialsUpdate
      description: 'Updates an existing credential.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialRequest'
      responses:
        '200':
          description: JSON describing the updated credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Credentials
      summary: Delete credential
      operationId: credentialsDeleteById
      description: 'Deletes credential.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      responses:
        '204':
          description: Deleted
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{clientId}/revoke:
    put:
      tags:
      - Credentials
      summary: Revoke credential
      operationId: credentialsRevoke
      description: 'Revoke an existing credential.

        ### Authorization Required:

        - Designer Administrator'
      parameters:
      - $ref: '#/components/parameters/CredentialId'
      responses:
        '204':
          description: Revoked
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    CredentialId:
      name: clientId
      in: path
      description: Unique client ID
      required: true
      schema:
        type: string
  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
    CredentialResponse:
      type: object
      required:
      - clientId
      - name
      - role
      - roles
      - created
      - status
      - credentialType
      properties:
        clientId:
          type: string
          description: Client ID of the credential.
        name:
          type: string
          description: Name of the credential.
        role:
          type: string
          description: Express role of the credential.
        roles:
          type: array
          items:
            type: string
          description: Creator or Express roles of the credential.
        groups:
          type: array
          items:
            type: string
          description: Express groups of the credential.
        applicationRoles:
          type: object
          description: Application Express roles of the credential.
        created:
          type: string
          description: Date of when the credential was created.
        modified:
          type: string
          description: Date of when the credential was modified.
        status:
          type: string
          description: Status of the credential.
        credentialType:
          type: string
          description: Type of the credential (Creator or Express).
        expireDate:
          type: string
          description: Date of when the credential expires.
    CredentialRequest:
      type: object
      required:
      - clientId
      - clientSecret
      - name
      properties:
        clientId:
          type: string
          description: Client ID of the credential.
        clientSecret:
          type: string
          description: Client secret of the credential.
        description:
          type: string
          description: Description of the credential.
        designerRoles:
          type: string
          description: Creator roles of the credential.
        expressRoles:
          type: string
          description: Express roles of the credential.
        name:
          type: string
          description: Name of the credential.
  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