openapi: 3.0.0
servers:
  - url: 'https://api.devbank.apiture.com/apiKeys'
info:
  title: API Keys
  description: >
    API Keys provide [secure access](https://developer.apiture.com/docs/secure-access/) to Apiture APIs. Each client application requires a unique API
    key to access the APIs in each runtime API environment (such as `api.canapi.bank`, `api.devbank.apiture.com`, or `api.3rdparty.bank`).


    The API Key resource managed by this API creates the following:

     * The API Key which is passed in the `API-Key` request header of
       each API call;
     * A unique Client ID and Client Secret (also known as _client credentials_)
       with which the client application
       can authenticate with the authentication endpoints in the service.

    Each key resource requires a _client application_ and a target runtime _api environment_ when constructing the API key. These resources are passed
    in the `createKey` operation via links in the request body via the [link relations](http://developer.apiture.com/docs/concepts/links/):

     * `apiture:clientApplication`
     * `apiture:environment`

    The client application may be associated with a partner organization (business).


    Each key may be in one of several states (`pending`, `active`, `inactive`); Keys are initially created in the `pending` state. State transitions
    are performed by a `POST` via the `activateKey`,  `deactivateKey` operations using the links in the key resource:

     * `apiture:activate`
     * `apiture:deactivate`

    which must be initially performed by a administrator with permission to approve keys. Users may deactivate/reactivate keys after they have been
    approved. Deactivating a key is also called _revoking_ a key.


    When a client application is deactivated, all its associated keys and client credentials are deactivated.


    When a client application is activated, all its associated keys and client credentials are activated.


    When a client application is deleted, all its associated keys and client credentials are deleted.

    There are five types of keys

     * The Discoverer Key (`discoverer`) is for unauthenticated users to explore
       the Apiture APIs in a limited manner, using a sample
       user ("John Smith") identity. The Discoverer Key
       is shared by all unauthenticated users.
       It is recycled on a periodic basis:
       a new Discoverer key is minted each day to replace the old one,
       and the old one is then revoked, marked as expired, and deleted at some time
       after that.
     * An Explorer key (`explorer`) is for authenticated users to explore
       the Apiture APIs in more depth. It is provisioned after
       a user registers (moderated by the portal admin).
       Using this, the developer can also create sample
       data that only they can access (bank accounts, etc.).
       The user can view their Explorer key via their
       My Account page on the developer portal.
     * Partner keys (`partner`) are associated with a specific
       client partner organization (company), a
       registered client application, and
       a specific runtime environment (such
       as a dev, test, or other environment.
     * Production keys (`production`) are partner keys that are attached
       to a production (non-test, non-development) environment.
     * Private keys (`private`) are for Apiture use only.

    This API provides convenient operations for creating or accessing Discoverer and Explorer keys.


    # Error Types


    Error responses in this API may have one of the `type` values described below.

    See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information

    on error responses and error types.




    <h2 class='errorType' id="err-invalidPartnerDomain">invalidPartnerDomain</h2>


    **Description**: The current user's email address is associated with a restricted partner organization domain. <br>

    **Remediation**: Register using a company email address, not an email service.



    <h2 class='errorType' id="err-keyRefNotFound">keyRefNotFound</h2>


    **Description**: The key parameter was malformed or does not refer to an existing or accessible key. <br>

    **Remediation**: Pass a valid key in the key query parameter.



    <h2 class='errorType' id="err-passwordRequired">passwordRequired</h2>


    **Description**: When updating the discoverer key credentials, the `sampleUserPassword` property is required if the request incldues the
    `sampleUserName`. <br>

    **Remediation**: Pass `sampleUserPassword` if the request incldues the `sampleUserName`.
  version: 0.26.0
  contact:
    name: Apiture
    url: 'https://developer.apiture.com'
    email: api@apiture.com
  termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
  - name: Key
    description: Keys for secure API access.
  - name: Key States
    description: Change the state of API keys.
  - name: Discoverer Key
    description: Access to Discoverer Keys
  - name: Explorer Key
    description: Access to Explorer Keys
  - name: API
    description: Endpoints which describe this API.
paths:
  /activeKeys:
    post:
      operationId: activateKey
      security:
        - apiKey: []
          accessToken:
            - data/write
      summary: Activate a key
      description: >-
        Attempt to activate a key. <br> For non-administrators, this submits a request to the portal administrators to approve or reject the request.
        This may also change the state to `pending`. The corresponding response code is 200. <br> For administrator users, this action changes the
        state directly (if the state can be changed to `active` or is already `active`). The API key is also deployed into the target environment. The
        corresponding response code is 200. <br> This operation is available via the `apiture:activate` link on the key resource, if and only if the
        key is eligible for the activate operation. The response is the updated representation of the key.
      tags:
        - Key States
      parameters:
        - $ref: '#/components/parameters/keyQueryParam'
        - $ref: '#/components/parameters/noNotificationQueryParam'
      responses:
        '200':
          description: OK. The operation succeeded.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '202':
          description: Accepted. The request to activate a key has been accepted. The state may change to `pending` while the request is processed.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400ActivateKey'
        '409':
          $ref: '#/components/responses/409ActivateKeyConflict'
  /inactiveKeys:
    post:
      operationId: deactivateKey
      security:
        - apiKey: []
          accessToken:
            - data/write
      summary: Deactivate a key
      tags:
        - Key States
      description: >-
        Update a key by adding it to the set of inactive keys. This changes the `state` property of the key to `inactive`. This operation is available
        via the `apiture:deactivate` link on the key resource, if and only if the key is eligible for the deactivate operation. The API key is also
        removed from the target environment. The response is the updated representation of the key.
      parameters:
        - $ref: '#/components/parameters/keyQueryParam'
        - $ref: '#/components/parameters/noNotificationQueryParam'
      responses:
        '200':
          description: OK. The operation succeeded. The key was updated and its `state` changed to `inactive`.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400DeactivateKey'
        '409':
          $ref: '#/components/responses/409DeactivateKeyConflict'
  /keys:
    get:
      summary: Return a collection of keys
      description: >-
        Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [filterable](http://developer.apiture.com/docs/concepts/filtering)
        collection of keys. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links.

        The authenticated user can only access keys for applications in their partner domain (i.e. developers registered with validated emails with a
        `@mycompany.com` email domain can only see keys for that company), the discoverer key, and their own explorer key.
      operationId: getKeys
      security:
        - apiKey: []
          accessToken:
            - data/read
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/startQueryParam'
        - name: limit
          in: query
          description: The maximum number of key representations to return in this page.
          schema:
            type: integer
            format: int32
            default: 100
        - name: application
          in: query
          description: >-
            Filter API keys to only those for this client application. The value is the client application ID. This value is merged with the
            `?filter=` parameter (if any) and `?environment=` parameter (if any) with an implicit `and`.
          schema:
            type: string
        - name: partner
          in: query
          description: >-
            Filter API keys to only those for this partner organization. The value is the partner ID or partner domain. This value is merged with the
            `?filter=` parameter (if any) and `?environment=` parameter (if any) with an implicit `and`.
          schema:
            type: string
        - name: environment
          in: query
          description: >-
            Filter API keys to only those for this environment. The value is the environment ID. This value is merged with the `?filter=` parameter
            and `?application` or `?partner` parameter with an implicit `and`.
          schema:
            type: string
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/stateQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/keys'
            application/json:
              schema:
                $ref: '#/components/schemas/keys'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
    post:
      summary: Create a new key
      description: >-
        Create a new key in the `keys` collection. The key's `state` is initially `pending` but will change to `active` when the key has been deployed
        in the target environment.

        The associated client application and the target API environment to must be passed in the `href` of the corresponding `_links` in the request:

         * `apiture:clientApplication`
         * `apiture:environment`

        This fails if there is an existing key in the  `pending`, `active` or `inactive` state for the named client application and API environment.
        The key's `type` is set to `partner` or `production`, depending on the type of the key's environment.
      operationId: createKey
      security:
        - apiKey: []
          accessToken:
            - data/write
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/noNotificationQueryParam'
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: >-
                The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
                *`scheme`*`://host`
              schema:
                type: string
                format: uri
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403Key'
        '409':
          $ref: '#/components/responses/409Key'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/createKey'
          application/json:
            schema:
              $ref: '#/components/schemas/createKey'
        description: The data necessary to create a new key.
        required: true
  '/keys/{keyId}':
    get:
      summary: Fetch a representation of this key
      description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this key resource.'
      operationId: getKey
      security:
        - apiKey: []
          accessToken:
            - data/read
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/keyIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '404':
          $ref: '#/components/responses/404Key'
    put:
      summary: Update this key
      description: Perform a complete replacement of this key.
      operationId: updateKey
      security:
        - apiKey: []
          accessToken:
            - data/write
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/keyIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404Key'
        '422':
          $ref: '#/components/responses/422'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/key'
          application/json:
            schema:
              $ref: '#/components/schemas/key'
        required: true
    patch:
      summary: Update this key
      description: Perform a partial update of this key. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included.
      operationId: patchKey
      security:
        - apiKey: []
          accessToken:
            - data/write
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/keyIdPathParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404Key'
        '422':
          $ref: '#/components/responses/422'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/key'
          application/json:
            schema:
              $ref: '#/components/schemas/key'
        required: true
    delete:
      summary: Delete this key resource
      description: Delete this key resource and any resources that are owned by it.
      operationId: deleteKey
      security:
        - apiKey: []
          accessToken:
            - data/delete
      x-apiture-implemented: true
      tags:
        - Key
      parameters:
        - $ref: '#/components/parameters/keyIdPathParam'
      responses:
        '204':
          $ref: '#/components/responses/204Deleted'
  /discovererKey:
    get:
      summary: Return the Discoverer Key
      description: >-
        Returns the active Discoverer Key. If the Discoverer Key has not been created, this call creates, activates, and returns it. The key's `type`
        is set to `discoverer`. If the key exists, it is returned.

        The Discoverer Key is associated with the Dev Portal application and is only valid in the DevBank environment.
      operationId: getDiscovererKey
      tags:
        - Discoverer Key
      security:
        - apiKey: []
      x-apiture-implemented: true
      responses:
        '200':
          description: OK.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/discovererKey'
            application/json:
              schema:
                $ref: '#/components/schemas/discovererKey'
        '404':
          description: Not Found; the Discoverer Key has not been created yet.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    post:
      summary: Create or recycle the Discoverer Key
      description: |-
        Creates or recycles the Discoverer Key.
        If the Discoverer Key has not been created, this call
        creates, activates, and returns it.
        If the key exists, the old key is recycled (scheduled
        to be removed but left active) and a new Discoverer key is created, activated, and returned.


        If the request body contains new credentials for the sample user,
        the service saves those new credentials used for creating the discoverer key and
        discoverer access token.


        The Discoverer Key is associated with the Dev Portal
        application and is only valid in the DevBank environment.


        *Only the administrator or system can create or recycle the discoverer key.*
      operationId: discovererKey
      tags:
        - Discoverer Key
      security:
        - apiKey: []
          accessToken:
            - admin/read
            - admin/write
      x-apiture-implemented: true
      responses:
        '200':
          description: OK.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '201':
          description: Created
          headers:
            Location:
              description: The URL of the new Explorer key
              schema:
                type: string
                format: uri
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '400':
          $ref: '#/components/responses/400'
        '403':
          description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '422':
          description: |-
            Unprocessable Entity. The request body could not be processed.

            This error response may have one of the following `type` values:
            * [`passwordRequired`](#err-passwordRequired)
          x-apiture-errors:
            - passwordRequired
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/discoverKeyRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/discoverKeyRequest'
        description: >-
          Optional credentials to reset the user name and password of the sample user used for creating/refreshing the discoverer key and access
          token.
        required: true
  /explorerKey:
    get:
      summary: Return the user's Explorer Key
      description: >-
        Returns the user's Explorer Key for a target environmet.


        An Explorer Key is associated with the Dev Portal application client application and one of the target environments associated with the dev
        portal. (Thus, a user may have multiple explorer keys, one per environment.)
      operationId: getExplorerKey
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - data/read
      parameters:
        - $ref: '#/components/parameters/environmentQueryParam'
      x-apiture-implemented: true
      responses:
        '200':
          description: OK.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '403':
          description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not Found; the Explorer Key has not been created yet.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    post:
      summary: Create or recycles the user's Explorer Key
      description: >-
        Creates and returns the user's Explorer Key. If the Explorer Key has not been created, this call creates and returns it, but leaves it in a
        `pending` state, awaiting administrator approval. If the key exists, the old key is recycled (scheduled to be removed but left active) and a
        new Explorer key is created, activated, and returned. The key's `type` is set to `explorer`.


        The Explorer Key is specific and private to the current authenticated user. It has a `name` which is the concatenation of the user's user name
        (email address), `"Explorer"`, such as `"walter.black@cool.example.com Explorer"`.


        The Explorer Key is associated with the Dev Portal application and is only valid in the DevBank environment or where the domain name of the
        user's email address is listed in the API environment's `domains`.
      operationId: explorerKey
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - data/read
            - data/write
      parameters:
        - $ref: '#/components/parameters/environmentQueryParam'
      x-apiture-implemented: true
      responses:
        '200':
          description: OK.
          headers:
            Location:
              description: The URL of the new Explorer key
              schema:
                type: string
                format: uri
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '201':
          description: Created
          headers:
            Location:
              description: The URL of the new Explorer key
              schema:
                type: string
                format: uri
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/key'
            application/json:
              schema:
                $ref: '#/components/schemas/key'
        '403':
          description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /explorerKey/sampleDataGeneration:
    post:
      summary: Create sample data for the user
      description: |-
        Create sample data for the user using their explorer key.
        This operation is only called from `createSampleDataRequest`
        to start the data generation asynchronously.
        This operation does not use a request body.


        **Note** This operation will move from this API to
        a dev portal `users` API, but that API does not yet exist.
      operationId: generateSampleData
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - data/read
            - data/write
      parameters:
        - name: requestId
          in: query
          required: true
          description: >-
            A reference to the internal sample data request containing the user, explorer key, environment, and environment token. This `requestId` is
            generated from the [`createSampleDataRequest`](#op-createSampleDataRequest) operation.
          schema:
            type: string
      responses:
        '202':
          description: Accepted. The request was accepted and will be processed.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
            application/json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
  /explorerKey/sampleDataRequest:
    get:
      summary: Check sample data request status
      description: |-
        Return the status of the sample data request
        for an environment. The `state` property conveys the status
        of the request.


        **Note** This operation will move from this API to
        a dev portal `users` API, but that API does not yet exist.
      operationId: checkSampleDataRequest
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - data/read
      parameters:
        - $ref: '#/components/parameters/environmentQueryParam'
        - $ref: '#/components/parameters/environmentTokenQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
            application/json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
        '400':
          $ref: '#/components/responses/400'
    post:
      summary: Create sample data for the user
      description: |-
        Create sample data for the user using their explorer key.
        This creates an account for the user
        and then runs the transaction tool to create some
        finctional historical transactions for the user.
        If invoked multiple times, it will run the processes
        again. This operation is asynchronous.
        The explorer key must be `active`.
        This operation does not use a request body.


        **Note** This operation will move from this API to
        a dev portal `users` API, but that API does not yet exist.
      operationId: createSampleDataRequest
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - data/read
            - data/write
      parameters:
        - $ref: '#/components/parameters/environmentQueryParam'
        - $ref: '#/components/parameters/environmentTokenQueryParam'
      responses:
        '202':
          description: Accepted. The request was accepted and will be processed.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
            application/json:
              schema:
                $ref: '#/components/schemas/sampleDataRequest'
        '400':
          $ref: '#/components/responses/400'
        '409':
          description: 'Conflict. The process is already running, or the explorer key is not active, or some other situation prevents creating sample data.'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /explorerKey/sampleDataRequest/counter:
    post:
      summary: Reset a user's sample data request counter
      description: >-
        The API enforces a limit of the number of times a user may request sample data. However, if the sample generation fails repeatedly for the
        user, they may reach the limit without any data being generated for them. An administrator can use this operation to reset the counter back to
        zero so the user can try again.
      operationId: resetSampleDataRequestCounter
      tags:
        - Explorer Key
      security:
        - apiKey: []
          accessToken:
            - admin/write
      responses:
        '202':
          description: Accepted. The request was accepted and will be processed.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/sampleDataCounterReset'
            application/json:
              schema:
                $ref: '#/components/schemas/sampleDataCounterReset'
        '400':
          $ref: '#/components/responses/400'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/sampleDataCounterReset'
          application/json:
            schema:
              $ref: '#/components/schemas/sampleDataCounterReset'
        description: Request resetting the samle data counter back to zero for a user.
        required: true
  /explorerKeys:
    get:
      summary: Get a Explorer Keys
      description: Return the explorer keys for a partner domain or user. This is an admin-only operation.
      operationId: getExplorerKeys
      security:
        - apiKey: []
          accessToken:
            - admin/read
      x-apiture-implemented: true
      tags:
        - Explorer Key
      parameters:
        - name: owner
          description: Filter API keys to only those keys for this owner's email address.
          in: query
          schema:
            type: string
            format: email
        - name: environment
          in: query
          description: 'Filter API keys to only those keys whose environment ID, name, or hostname match this value.'
          schema:
            type: string
        - $ref: '#/components/parameters/stateQueryParam'
        - name: filter
          in: query
          description: >-
            Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).<br>This collection may be filtered by
            following properties and functions:
          schema:
            type: string
        - $ref: '#/components/parameters/startQueryParam'
        - name: limit
          in: query
          description: The maximum number of key representations to return in this page.
          schema:
            type: integer
            format: int32
            default: 100
      x-apiture-traits:
        filtering:
          owner:
            filters: 'eq, in, contains'
          partner:
            filters: 'eq, in, contains'
          environment:
            filters: 'eq, in, contains'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/explorerKeys'
            application/json:
              schema:
                $ref: '#/components/schemas/explorerKeys'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
  /:
    get:
      summary: Top-level resources and operations in this API
      description: Return links to the top-level resources and operations in this API.
      operationId: getApi
      security:
        - apiKey: []
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/root'
            application/json:
              schema:
                $ref: '#/components/schemas/root'
      tags:
        - API
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      security:
        - apiKey: []
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
            application/openapi+json;version=2.0:
              schema:
                type: object
            application/openapi+yaml;version=2.0:
              schema:
                type: object
            application/hal+json:
              schema:
                type: object
      tags:
        - API
x-apiture-errors:
  passwordRequired:
    description: 'When updating the discoverer key credentials, the `sampleUserPassword` property is required if the request incldues the `sampleUserName`.'
    remediation: Pass `sampleUserPassword` if the request incldues the `sampleUserName`.
  keyRefNotFound:
    description: The key parameter was malformed or does not refer to an existing or accessible key.
    remediation: Pass a valid key in the key query parameter.
  invalidPartnerDomain:
    description: The current user's email address is associated with a restricted partner organization domain.
    remediation: 'Register using a company email address, not an email service.'
x-apiture-traits:
  - api:
      title: API Keys
      basePath: apiKeys
      description: Manage API keys for secure API access.
      links:
        - getApi
        - getApiDoc
        - getKeys
        - createKey
        - getDiscovererKey
        - discovererKey
        - getExplorerKey
        - explorerKey
      applied: true
  - resource:
      name: key
      description: 'An API Key, for secure access to Apiture APIs'
      etag: false
      simpleModelSchema: true
      sortable: false
      searchable: false
      cursor: true
      applied: true
  - state:
      state: inactive
      verb: deactivate
      name: key
      applied: true
  - state:
      state: active
      verb: activate
      name: key
      applied: true
x-apiture-annotated-at: '2020-10-23T17:06:33.888Z'
components:
  schemas:
    keyFields:
      title: Key Fields (v1.0.0)
      description: Properties used in other API key schemas.
      x-apiture-fragment: true
      type: object
      properties:
        name:
          description: >-
            The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
            organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
          type: string
          minLength: 6
          maxLength: 128
      x-apiture-version: 1.0.0
      x-apiture-flattened: true
    createKey:
      title: Create Key (v1.0.0)
      description: >
        Request body to create a new API key. The request **must** contain links as described in the `createKey` schema. The `type` of the key is
        determined by the environment's type.



        <h3 class='schema-links' id="createKey-links" >Links</h3>


        Response and request bodies using this <strong><code>createKey</code></strong> schema may contain

        the following <a href='https://developer.apiture.com/docs/concepts/links'>links</a>:


        <table>

        <tr>
          <th>Rel</th><th>Summary</th><th>Method</th>
        </tr>


        <tr>

        <td><strong><code>apiture:clientApplication</code></strong></td>

        <td></td><td><code>GET</code></td>


        <tr>

        <td><strong><code>apiture:environment</code></strong></td>

        <td></td><td><code>GET</code></td>

        </table>
      x-apiture-links:
        - rel: 'apiture:clientApplication'
          summary: 'Client application  (`/clientApplications/applications/{applicationId}`)'
        - rel: 'apiture:environment'
          summary: 'API Environment resource (`apiEnvironments/environments/{environmentId}`)'
      example:
        name: 3rd Party Bank web application at api.3rdparty.bank (production)
        _links:
          'apiture:clientApplication':
            href: 'https://api.developer.apiture.com/clientApplications/applications/dd5122bd-a8cd-4d23-a001-d29fcdf346cc'
          'apiture:environment':
            href: 'https://api.developer.apiture.com/apiEnvironments/environments/d85d9eb2-4d4b-4cdf-8b69-5a3ea0ddfaac'
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - $ref: '#/components/schemas/keyFields'
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        name:
          description: >-
            The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
            organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
          type: string
          minLength: 6
          maxLength: 128
      type: object
      x-apiture-flattened: true
    key:
      title: Key (v1.0.0)
      description: |
        API key resources.


        <h3 class='schema-links' id="key-links" >Links</h3>

        Response and request bodies using this <strong><code>key</code></strong> schema may contain
        the following <a href='https://developer.apiture.com/docs/concepts/links'>links</a>:

        <table>
        <tr>
          <th>Rel</th><th>Summary</th><th>Method</th>
        </tr>

        <tr>
        <td><a href='#op-activateKey'><strong><code>apiture:activate</code></strong></a></td><td>Activate a key</td><td><code>POST</code></td>
        </tr>

        <tr>
        <td><a href='#op-deactivateKey'><strong><code>apiture:deactivate</code></strong></a></td><td>Deactivate a key</td><td><code>POST</code></td>
        </tr>
        </table>
      example:
        _profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
        _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
        name: My Apiture POC
        key: 295fd0e8b0b449f9a5a3dbfd4a3e3149
        clientId: 1b97ad67397640c89208bdfd1e039b1f
        clientSecret: 5035cef945054f96a56d07620652b6bf
        applicationName: My Apiture POC
        partnerName: Example FinTex
        partnerDomain: fintech.example.com
        _links:
          'apiture:clientApplication':
            href: 'https://api.developer.apiture.com/clientApplications/applications/00aaf46d-05c2-4237-9305-fd9ed9c4994b'
          'apiture:partner':
            href: 'https://api.developer.apiture.com/partners/organizations/2435a7f0-2650-49df-9988-c113e36e3c96'
          'apiture:environment':
            href: 'https://api.developer.apiture.com/apiEnvironments/environments/8c112888-f139-4583-bb0e-cbd378550a48'
          'apiture:deactivate':
            href: 'https://api.developer.apiture.com/apiKeys/inactiveKeys?key=0399abed-fd3d-4830-a88b-30f38b8a365c'
      x-apiture-links:
        - rel: 'apiture:activate'
          operationId: activateKey
        - rel: 'apiture:deactivate'
          operationId: deactivateKey
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - $ref: '#/components/schemas/keyFields'
        - properties:
            - _id
            - key
            - applicationName
            - environmentName
            - environmentHost
            - partnerName
            - partnerDomain
            - clientId
            - clientSecret
            - type
            - state
            - createdAt
            - expiresAt
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        name:
          description: >-
            The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
            organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
          type: string
          minLength: 6
          maxLength: 128
        _id:
          description: The resource ID of this API key resource. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
          type: string
          minLength: 6
          maxLength: 40
          readOnly: true
        key:
          description: 'The value of the API key, to be used in the `API-Key` request header on API calls.'
          type: string
          minLength: 6
          maxLength: 64
          readOnly: true
        applicationName:
          description: >-
            The name of the client application for this API key. This is derived from the `apiture:clientApplication` resource passed in at creation
            time.
          type: string
          minLength: 4
          maxLength: 64
          example: My Apiture POC
          readOnly: true
        environmentName:
          description: 'The name of the API environment for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
          type: string
          minLength: 6
          maxLength: 64
          example: DevBank
          readOnly: true
        environmentHost:
          description: 'The name of the API environment host for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
          type: string
          minLength: 4
          maxLength: 64
          example: api.devbank.apiture.com
          readOnly: true
        partnerName:
          description: The name of the optional partner organization/company. This is derived from the partner organization associated with the application.
          type: string
          minLength: 4
          maxLength: 128
          readOnly: true
          example: Example FinTex
        partnerDomain:
          description: >-
            The web domain of the optional partner organization/company. This is derived from the partner organization associated with the
            application.
          type: string
          minLength: 4
          maxLength: 128
          example: fintech.example.com
          readOnly: true
          format: urn
        clientId:
          description: The client ID porton of the client credentials associated with the API key.
          type: string
          minLength: 6
          maxLength: 128
          readOnly: true
        clientSecret:
          description: The client secret porton of the client credentials associated with the API key.
          type: string
          minLength: 6
          maxLength: 128
          readOnly: true
        type:
          description: Defines what type of key this is.
          allOf:
            - $ref: '#/components/schemas/keyType'
          readOnly: true
        state:
          description: >-
            The current state of the key. This is immutable and derived, based on the actions to activate or deactivate the key via the `activateKey`
            and `deactivateKey` operations. The initial state is `pending`; it changes to `active` when the API key and credentials have been deployed
            into the target environment via the `activateKey` operation.
          allOf:
            - $ref: '#/components/schemas/keyState'
          readOnly: true
        createdAt:
          description: The date-time when the key was created. This is an RFC 3336 formatted string in UTC time.
          type: string
          format: date-time
          readOnly: true
          example: {}
        expiresAt:
          description: >-
            The date-time when the key expires. If this is omitted, the key does not have an expiration time. (This expiration is typically is used
            only for Discoverer keys). This is an RFC 3336 formatted string in UTC time.
          type: string
          format: date-time
          readOnly: true
          example: {}
      type: object
      x-apiture-flattened: true
    keyState:
      title: Key State (v1.0.0)
      description: |+
        Possible state of an API key.

        <strong><code>keyState</code></strong> strings may have one of the following
        [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):

        <table>
        <tr>
          <th>Value</th><th>Description</th>
        </tr>

        <tr>
            <td><strong><code>pending</code></strong></td><td>Pending: A key that has been requested but not activated (not approved).</td>
            </tr>
        <tr>
            <td><strong><code>active</code></strong></td><td>Active: A key that has been approved and is active.</td>
            </tr>
        <tr>
            <td><strong><code>inactive</code></strong></td><td>Inactive: A key that has been revoked and is not active.</td>
            </tr>
        </table>

      type: string
      x-apiture-enum: keyState
      enum:
        - pending
        - active
        - inactive
      x-apiture-version: 1.0.0
      x-apiture-flattened: true
    keyType:
      title: Key Type (v1.0.0)
      description: |+
        The type describe the purpose and use of the API key. This field is derived from the target environment used when the key is created.

        <strong><code>keyType</code></strong> strings may have one of the following
        [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):

        <table>
        <tr>
          <th>Value</th><th>Description</th>
        </tr>

        <tr>
            <td><strong><code>discoverer</code></strong></td><td>Discoverer Key: The Discoverer Key is for unauthenticated users to explore the Apiture APIs in a limited manner, using a sample user ("John Smith") identity. The Discoverer Key is shared by all unauthenticated users. It is recycled on a periodic basis: a new Discoverer key is minted each day to replace the old one, and the old one is then revoked, marked as expired, and deleted at some time after that.</td>
            </tr>
        <tr>
            <td><strong><code>explorer</code></strong></td><td>Explorer Key: An Explorer key is for authenticated users to explore
         the Apiture APIs in more depth. It is provisioned after
         a user registers (moderated by the portal admin).
         Using this, the developer can also create sample
         data that only they can access (bank accounts, etc.).
         The user can view their Explorer key via their
         My Account page on the developer portal.</td>
            </tr>
        <tr>
            <td><strong><code>partner</code></strong></td><td>Partner Key: Partner keys are associated with a specific client partner organization (company), a registered client application, and a specific runtime environment (such as a dev, test, or other environment.</td>
            </tr>
        <tr>
            <td><strong><code>production</code></strong></td><td>Production Key: Production keys are partner keys that are attached to a production (non-test, non-development) environment.</td>
            </tr>
        <tr>
            <td><strong><code>private</code></strong></td><td>Private Key: Private keys are for Apiture use only.</td>
            </tr>
        </table>

      type: string
      x-apiture-enum: keyType
      enum:
        - discoverer
        - explorer
        - partner
        - production
        - private
      x-apiture-version: 1.0.0
      x-apiture-flattened: true
    discovererKey:
      title: Discoverer Key (v1.0.0)
      description: An API key and access token for an unauthenticated user to make API calls against the devbank target environment.
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - apiKey
            - accessToken
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        apiKey:
          description: The API key for Discoverer use.
          allOf:
            - $ref: '#/components/schemas/key'
        accessToken:
          description: >-
            An OAuth access token which may be used for API calls on the devbank envirornment. This token expires every hour. The client should fetch
            a new access token before this expires.
          type: string
      type: object
      x-apiture-flattened: true
    explorerKeys:
      title: Explorer Keys List (v1.0.0)
      description: Collection of explorer keys.
      example:
        _profile: 'https://api.apiture.com/schemas/apiKeys/explorerKeys/v1.0.0/profile.json'
        start: g434ljkf430
        limit: 10
        name: keys
        _links:
          self:
            href: 'https://api.developer.apiture.com/apiKeys/explorerKeys'
          next:
            href: 'https://api.developer.apiture.com/apiKeys/keys?start=p4900sk3df9&limit=10'
        _embedded:
          items:
            _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            owner: Walter.Black@example.com
            _profile: 'https://api.apiture.com/schemas/apiKeys/explorerKey/v1.0.0/profile.json'
            name: Explorer Key Walter.Black@example.com
            key: 295fd0e8b0b449f9a5a3dbfd4a3e3149
            clientId: 1b97ad67397640c89208bdfd1e039b1f
            clientSecret: 5035cef945054f96a56d07620652b6bf
            applicationName: Dev Portal
            partnerName: Example
            partnerDomain: example.com
            _links:
              'apiture:clientApplication':
                href: 'https://api.developer.apiture.com/clientApplications/applications/00aaf46d-05c2-4237-9305-fd9ed9c4994b'
              'apiture:partner':
                href: 'https://api.developer.apiture.com/partners/organizations/2435a7f0-2650-49df-9988-c113e36e3c96'
              'apiture:environment':
                href: 'https://api.developer.apiture.com/apiEnvironments/environments/8c112888-f139-4583-bb0e-cbd378550a48'
              'apiture:deactivate':
                href: 'https://api.developer.apiture.com/apiKeys/inactiveKeys?key=0399abed-fd3d-4830-a88b-30f38b8a365c'
              self:
                href: 'https://api.developer.apiture.com/apiKeys/keys/0399abed-fd3d-4830-a88b-30f38b8a365c'
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/cursorPagedCollection'
        - properties:
            - _embedded
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          type: object
          description: Embedded objects.
          properties:
            items:
              description: An array containing a page of key items.
              type: array
              items:
                $ref: '#/components/schemas/explorerKey'
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        start:
          description: >-
            An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
            to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
          type: string
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: A name for the items in collection.
          type: string
      type: object
      x-apiture-flattened: true
    explorerKey:
      title: Explorer Key (v1.0.0)
      description: A user's explorer key.
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/key'
        - properties:
            - owner
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        name:
          description: >-
            The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
            organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
          type: string
          minLength: 6
          maxLength: 128
        _id:
          description: The resource ID of this API key resource. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
          type: string
          minLength: 6
          maxLength: 40
          readOnly: true
        key:
          description: 'The value of the API key, to be used in the `API-Key` request header on API calls.'
          type: string
          minLength: 6
          maxLength: 64
          readOnly: true
        applicationName:
          description: >-
            The name of the client application for this API key. This is derived from the `apiture:clientApplication` resource passed in at creation
            time.
          type: string
          minLength: 4
          maxLength: 64
          example: My Apiture POC
          readOnly: true
        environmentName:
          description: 'The name of the API environment for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
          type: string
          minLength: 6
          maxLength: 64
          example: DevBank
          readOnly: true
        environmentHost:
          description: 'The name of the API environment host for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
          type: string
          minLength: 4
          maxLength: 64
          example: api.devbank.apiture.com
          readOnly: true
        partnerName:
          description: The name of the optional partner organization/company. This is derived from the partner organization associated with the application.
          type: string
          minLength: 4
          maxLength: 128
          readOnly: true
          example: Example FinTex
        partnerDomain:
          description: >-
            The web domain of the optional partner organization/company. This is derived from the partner organization associated with the
            application.
          type: string
          minLength: 4
          maxLength: 128
          example: fintech.example.com
          readOnly: true
          format: urn
        clientId:
          description: The client ID porton of the client credentials associated with the API key.
          type: string
          minLength: 6
          maxLength: 128
          readOnly: true
        clientSecret:
          description: The client secret porton of the client credentials associated with the API key.
          type: string
          minLength: 6
          maxLength: 128
          readOnly: true
        type:
          description: Defines what type of key this is.
          allOf:
            - $ref: '#/components/schemas/keyType'
          readOnly: true
        state:
          description: >-
            The current state of the key. This is immutable and derived, based on the actions to activate or deactivate the key via the `activateKey`
            and `deactivateKey` operations. The initial state is `pending`; it changes to `active` when the API key and credentials have been deployed
            into the target environment via the `activateKey` operation.
          allOf:
            - $ref: '#/components/schemas/keyState'
          readOnly: true
        createdAt:
          description: The date-time when the key was created. This is an RFC 3336 formatted string in UTC time.
          type: string
          format: date-time
          readOnly: true
          example: {}
        expiresAt:
          description: >-
            The date-time when the key expires. If this is omitted, the key does not have an expiration time. (This expiration is typically is used
            only for Discoverer keys). This is an RFC 3336 formatted string in UTC time.
          type: string
          format: date-time
          readOnly: true
          example: {}
        owner:
          description: The email address of the owner.
          type: string
          format: email
      type: object
      x-apiture-flattened: true
    keys:
      title: Key Collection (v1.0.0)
      description: |-
        Collection of keys. The items in the collection are ordered in the `_embedded.items` array; the `name` is `keys`.
         The top-level `_links` object may contain pagination links: `self`, `next`, `prev`, `first`, `last`, `collection`.
      example:
        _profile: 'https://api.apiture.com/schemas/apiKeys/keys/v1.0.0/profile.json'
        start: g434ljkf430
        limit: 10
        name: keys
        _links:
          self:
            href: 'https://api.developer.apiture.com/apiKeys/keys?start=g434ljkf430&limit=10'
          next:
            href: 'https://api.developer.apiture.com/apiKeys/keys?start=p4900sk3df9&limit=10'
          collection:
            href: 'https://api.developer.apiture.com/apiKeys/keys'
        _embedded:
          items:
            anyOf:
              - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
                _profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
                _links:
                  self:
                    href: 'https://api.developer.apiture.com/apiKeys/keys/0399abed-fd3d-4830-a88b-30f38b8a365c'
              - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
                _profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
                _links:
                  self:
                    href: 'https://api.developer.apiture.com/apiKeys/keys/d62c0701-0d74-4836-83f9-ebf3709442ea'
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/cursorPagedCollection'
        - properties:
            - _embedded
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          type: object
          description: Embedded objects.
          properties:
            items:
              description: An array containing a page of key items.
              type: array
              items:
                $ref: '#/components/schemas/key'
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        start:
          description: >-
            An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
            to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
          type: string
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: A name for the items in collection.
          type: string
      type: object
      x-apiture-flattened: true
    discoverKeyRequest:
      title: Discover Key Request (v1.0.0)
      description: >-
        Data the admin can pass when creating or recycling the discoverer key. This is optional, but may contain new credentials for the sample user.
        If `sampleUserName` is passed, the request must also contain `sampleUserPassword`. If only `sampleUserPassword` is passed, the request will
        update the password for the current sample user.
      type: object
      properties:
        sampleUserName:
          description: The user name (login userid) of the user used for sample data. This user must exist in the devbank environment used by the portal.
          type: string
          format: email
          example: user.name@example.com
        sampleUserPassword:
          description: The password of the sample user.
          type: string
      x-apiture-version: 1.0.0
      x-apiture-flattened: true
    sampleDataRequest:
      title: Sample Data Request (v1.0.0)
      description: |
        Reflects a user's request to create sample data in an environment.


        <h3 class='schema-links' id="sampleDataRequest-links" >Links</h3>

        Response and request bodies using this <strong><code>sampleDataRequest</code></strong> schema may contain
        the following <a href='https://developer.apiture.com/docs/concepts/links'>links</a>:

        <table>
        <tr>
          <th>Rel</th><th>Summary</th><th>Method</th>
        </tr>

        <tr>
        <td><strong><code>apiture:environment</code></strong></td>
        <td></td><td><code>GET</code></td>
        </table>
      x-apiture-links:
        - rel: 'apiture:environment'
          summary: 'API Environment resource (`apiEnvironments/environments/{environmentId}`)'
      x-apiture-version: 1.0.0
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - state
            - environmentId
            - environmentName
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        state:
          description: The state of the sample data request.
          allOf:
            - $ref: '#/components/schemas/sampleDataRequestState'
        environmentId:
          description: The `_id` of the API environment.
          type: string
          maxLength: 64
        environmentName:
          description: The `name` of the API environment.
          type: string
          maxLength: 64
      type: object
      x-apiture-flattened: true
    sampleDataRequestState:
      title: Sample Data Request State (v1.0.0)
      description: The state of the sample data request.
      type: string
      enum:
        - none
        - started
        - completed
        - failed
      x-apiture-version: 1.0.0
      x-apiture-flattened: true
    sampleDataCounterReset:
      title: Sample Data Counter Reset (v1.0.0)
      description: A request to reset a user's sample data generation counter back to zero.
      x-apiture-version: 1.0.0
      required:
        - username
        - environment
      example:
        _profile: 'https://api.apiture.com/schemas/apiKeys/sampleDataCounterReset/v1.0.0/profile.json'
        username: max.peck@nasa.gov
        environment: api.devbank.apiture.com
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractRequest'
        - properties:
            - username
            - environment
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        username:
          description: The username (email address) that the user uses to login to the developer portal.
          type: string
          format: email
        environment:
          description: The host name of the target environment where the user is trying to generate sample data.
          type: string
          minLength: 8
          maxLength: 64
      type: object
      x-apiture-flattened: true
    errorResponse:
      x-apiture-version: 2.0.0
      title: Error Response (v2.0.0)
      description: |-
        Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.

        This schema was resolved from [`common/errorResponse`](https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json).
      example:
        _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
        _error:
          _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
          message: The value for deposit must be greater than 0.
          statusCode: 422
          type: positiveNumberRequired
          attributes:
            value: -125.5
          remediation: Provide a value which is greater than 0
          occurredAt: '2018-01-25T05:50:52.375Z'
          _links:
            describedby:
              href: 'https://api.apiture.com/errors/positiveNumberRequired'
          _embedded:
            errors: []
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    root:
      x-apiture-version: 2.0.0
      title: API Root (v2.0.0)
      description: |-
        A HAL response, with hypermedia `_links` for the top-level resources and operations in API.

        This schema was resolved from [`common/root`](https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json).
      example:
        id: apiName
        name: API name
        apiVersion: 1.0.0
        _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
        _links: {}
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - _id
            - name
            - apiVersion
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        _id:
          description: This API's unique ID.
          readOnly: true
          type: string
        name:
          type: string
          description: This API's name.
        apiVersion:
          type: string
          description: This API's version.
      type: object
      x-apiture-flattened: true
    abstractResource:
      x-apiture-version: 2.0.0
      title: Abstract Resource (v2.0.0)
      description: >-
        An abstract schema used to define other schemas for request and response bodies. This is a
        [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
        optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
        successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
        or any data fields, only `_error` and optionally `_links`.


        This schema was resolved from
        [`common/abstractResource`](https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json).
      example:
        _profile: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/profile.json'
        _links:
          self:
            href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractRequest'
        - properties:
            - _error
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    cursorPagedCollection:
      x-apiture-version: 2.0.0
      title: Cursor Paged Collection (v2.0.0)
      description: >-
        A collection of resources, or a page from a larger collection. This is an abstract model schema which is extended to define specific resource
        collections. Pages are referenced using an opaque string starting point named `start`. The `_links` in the collection may contain [pagination
        links](https://developer.apiture.com/docs/concepts/pagination):

          * the `next` link returns the next page of items. If there is no `next`
          link, the collection has been exhausted.
          * the `first` link returns to the beginning
          of the filtered/sorted collection.
          * the `collection` link returns
          to the beginning of the default collection with no explicit filter
          or sort criteria.

        Cursor paged collections can only paginate forwards contiguously (without skipping items or pages), or reset to the beginning of the
        collection. This pagination works for collections which are likely to change during pagination, such as adding data to the beginning of the
        collection's natural sort order. Examples include transactions or audit records.


        This schema was resolved from
        [`common/cursorPagedCollection`](https://production.api.apiture.com/schemas/common/cursorPagedCollection/v2.0.0/model.json).
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/cursorPagedCollection/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - start
            - limit
            - name
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        start:
          description: >-
            An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
            to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
          type: string
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: A name for the items in collection.
          type: string
      type: object
      x-apiture-flattened: true
    abstractRequest:
      x-apiture-version: 2.0.0
      title: Abstract Request (v2.0.0)
      description: >-
        An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
        representation, minus the `_error` defined in `abstractResource`.


        This schema was resolved from [`common/abstractRequest`](https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json).
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
      example:
        _profile: 'https://api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json'
        _links:
          self:
            href: 'https://api.devbank.apiture.com/applications/'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    links:
      title: Links (v1.0.0)
      x-apiture-version: 1.0.0
      description: |-
        An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.

        This schema was resolved from [`common/links`](https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json).
      type: object
      x-apiture-key: linkRelationName
      additionalProperties:
        $ref: '#/components/schemas/link'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    error:
      x-apiture-version: 2.0.0
      title: Error (v2.0.0)
      description: |-
        Describes an error in an API request or in a service called via the API.

        This schema was resolved from [`common/error`](https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json).
      required:
        - message
      properties:
        message:
          type: string
          description: A localized message string describing the error condition.
        _id:
          description: >-
            A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
            the source of the error). This is is an opaque string.
          readOnly: true
          type: string
        statusCode:
          description: The HTTP status code associate with this error.
          type: integer
          minimum: 100
          maximum: 599
          example: 422
        type:
          type: string
          description: >-
            An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
            render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
            Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
            `stringValueNotInAllowedSet`.
        occurredAt:
          type: string
          format: date-time
          description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
          example: '2018-02-02T03:37:15.375Z'
        attributes:
          description: >-
            Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
            `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
            client/presentation tier). The set of attributes varies by error `type`.
          allOf:
            - $ref: '#/components/schemas/attributes'
        remediation:
          type: string
          description: An optional localized string which provides hints for how the user or client can resolve the error.
        errors:
          description: An optional array of nested error objects. This property is not always present.
          type: array
          items:
            $ref: '#/components/schemas/error'
        _links:
          $ref: '#/components/schemas/links'
      example:
        _id: 2eae46e1575c0a7b0115a4b3
        message: Descriptive error message...
        statusCode: 422
        type: errorType1
        remediation: Remediation string...
        occurredAt: '2018-01-25T05:50:52.375Z'
        errors:
          - _id: ccdbe2c5c938a230667b3827
            message: An optional embedded error
          - _id: dbe9088dcfe2460f229338a3
            message: Another optional embedded error
        _links:
          describedby:
            href: 'https://developer.apiture.com/errors/errorType1'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    attributes:
      x-apiture-version: 2.0.0
      title: Attributes (v2.0.0)
      description: |-
        An optional map of name/value pairs which contains additional dynamic data about the resource.

        This schema was resolved from [`common/attributes`](https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json).
      type: object
      x-apiture-key: attributeName
      additionalProperties:
        $ref: '#/components/schemas/attributeValue'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    link:
      x-apiture-version: 1.0.0
      title: Link (v1.0.0)
      description: >-
        Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
        links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
        links _may_ include a `method` property.


        This schema was resolved from [`common/link`](https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json).
      required:
        - href
      properties:
        href:
          type: string
          format: uri
          description: The URI or URI template for the resource/operation this link refers to.
        type:
          type: string
          description: The media type for the resource.
        templated:
          type: boolean
          description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
        title:
          type: string
          description: An optional human-readable localized title for the link.
        deprecation:
          type: string
          format: uri
          description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
        profile:
          type: string
          format: uri
          description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
      example:
        href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
        title: Application
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    attributeValue:
      x-apiture-version: 2.0.0
      title: Attribute Value (v2.0.0)
      description: |-
        The data associated with this attribute.

        This schema was resolved from [`common/attributeValue`](https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json).
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      properties: {}
      x-apiture-flattened: true
  responses:
    '304':
      description: Not Modified. The resource has not been modified since it was last fetched.
    '400':
      description: >-
        Bad Request. The request body or one or more of the query parameters was not well formed.  The `_error` field in the response will contain
        details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '422':
      description: >-
        Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
        contain details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    403Key:
      description: |-
        Conflict. Cannot create a client application for a user without a valid partner organization.

        This error response may have one of the following `type` values:
        * [`invalidPartnerDomain`](#err-invalidPartnerDomain)
      x-apiture-errors:
        - invalidPartnerDomain
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409Key:
      description: >-
        Conflict. A key cannot be created for the corresponding client application and API environment; an existing key already exists in the
        `pending`, `inactive` or `active` state.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    400ActivateKey:
      description: |-
        Bad Request. The key parameter was malformed or does not refer to an existing or accessible key.

        This error response may have one of the following `type` values:
        * [`keyRefNotFound`](#err-keyRefNotFound)
      x-apiture-errors:
        - keyRefNotFound
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409ActivateKeyConflict:
      description: >-
        Conflict. The request to change the state of the key is not allowed. The `_error` field in the response will contain details about the request
        error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    400DeactivateKey:
      description: |-
        Bad Request. The key parameter was malformed or does not refer to an existing or accessible key.

        This error response may have one of the following `type` values:
        * [`keyRefNotFound`](#err-keyRefNotFound)
      x-apiture-errors:
        - keyRefNotFound
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409DeactivateKeyConflict:
      description: >-
        Conflict. The request to change the state of the key is not allowed. The `_error` field in the response will contain details about the request
        error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    404Key:
      description: >-
        Not Found. There is no such key resource at the specified `{keyId}`. The `_error` field in the response will contain details about the request
        error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    204Deleted:
      description: No Content. The resource was deleted successfully.
  parameters:
    environmentQueryParam:
      name: environment
      description: The target API environment ID or host name where the explorer key is deployed.
      in: query
      required: true
      schema:
        type: string
    environmentTokenQueryParam:
      name: environmentAccessToken
      description: >-
        The access token which grants the user access to the target environment. The (dev portal) application obtains this token when the user
        authenticates against the client environment.
      in: query
      required: true
      schema:
        type: string
    keyQueryParam:
      name: key
      required: true
      in: query
      description: >-
        A string which uniquely identifies a key which is to added to the `activeKeys` or `inactiveKeys` resource sets. This may be the unique `keyId`
        or the URI of the key.
      schema:
        type: string
    noNotificationQueryParam:
      name: noNotification
      in: query
      required: false
      description: >-
        If `true`, suppress the notification (typically, email) to the key/application owner or admin that a key has been created or the state of the
        API key has changed. If `false` (default), send the notification. Use `?noNotificaton=true` when activating/deacticvating a client application
        and the notification for that operation suffices (so the user does not receive too many emails all at once.)
      schema:
        type: boolean
        default: false
    keyIdPathParam:
      name: keyId
      description: The unique identifier of this key. This is an opaque string. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
      in: path
      required: true
      schema:
        type: string
    startQueryParam:
      name: start
      in: query
      description: >-
        Represents the first record of the page of results. This is supplied by the service when paginating items: the `next` link includes a
        `?start=` query parameter which refers to beginning of the next page of items.
      schema:
        type: string
    filterQueryParam:
      name: filter
      in: query
      description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
      schema:
        type: string
    stateQueryParam:
      name: state
      in: query
      description: >-
        Subset the resources to only those whose `state` matches the query, such as `?state=active`. The value may be a `|` separated list of states,
        such as `?state=pending|active` to match all resources whose `state` is either `pending` _or_ `active`. If `?filter=` is also used, the two
        are combined with an implicit `and()` operation.
      style: pipeDelimited
      schema:
        type: array
        items:
          type: string
          enum:
            - pending
            - active
            - inactive
  requestBodies:
    key:
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/key'
        application/json:
          schema:
            $ref: '#/components/schemas/key'
      required: true
  securitySchemes:
    apiKey:
      type: apiKey
      name: API-Key
      in: header
      description: >-
        API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
        `API-Key: {api-key}` request header.
    accessToken:
      type: oauth2
      description: >-
        OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
        `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
        passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
        returns a refresh token which the client should use to renew the access token before it expires.
      flows:
        authorizationCode:
          authorizationUrl: 'https://auth.devbank.apiture.com/auth/oauth2/authorize'
          tokenUrl: 'https://api.devbank.apiture.com/auth/oauth2/token'
          scopes:
            data/read: Read access to API keys.
            admin/write: Write (update) access to API keys.
            data/write: Write (update) access to API keys.
            admin/delete: Delete access to API keys.
            admin/full: Full access to API keys.
