openapi: 3.0.0
info:
  title: Access
  description: >-
    The Access API describes the roles and permissions for access to Apiture APIs.

    This API defines two primary resources:
      * A [**permission**](#op-getPermissions) allows a user access to an API operation or set of operations,
        such as accessing an account, reading account transactions, scheduling transfers and payments,
        adding beneficiaries, or approving an application. All API operations that require OAuth2 authentication
        require specific permissions.
      * A [**role**](#op-getRoles) represents an aggregation of permissions or other roles.
        Users may be assigned one or more roles, via the Users API and Operators API.

    Each role has a `name` (a programmatic identifier), a short readable `label`, a longer `description`, a `category`, assignability (to users), and a list of child nodes and
    direct permissions. [Fetching a role](#op-getRole) may also embed a full list of its _effective permissions_, which is the union of the set of the direct permissions in the
    role and the effective permissions of the direct child roles.


    There are three [categories](#schema-roleCategory) of users, and thus three categories of roles that may be assigned to users.

     1. Administrative users who manage the deployment (`system`).
     1. Financial Institution operators, such as
        the deposits manager, the wire room staff, customer support, and so on.
        These financial institution users employ administrative
        and back office applications to manage the financial institution's digital banking. (`operator`)
     1. Banking customers who hold accounts and use client applications to perform digital banking.
        (This is for future use). (`customer`)

    Roles and permissions are organized in a directed acyclic graph. Roles are the nodes in the graph and permissions are the leaves. Roles may have child roles and child
    permissions, but permissions may not have children. The graph has a maximum nesting depth (node ancestry) of six roles.

    This version of the API is read-only. Future releases will define operations for creating and updating roles and permissions.
  version: 0.5.0
  contact:
    name: Apiture
    url: https://developer.apiture.com
    email: api@apiture.com
  termsOfService: https://developer.apiture.com/open/Apiture-Open-API-License-Agreement.pdf
servers:
  - url: https://api.devbank.apiture.com/access
tags:
  - name: Permissions
    description: Permissions for API Access
  - name: Roles
    description: User Roles for API Access
  - name: API
    description: The Access API
paths:
  /myAccess:
    get:
      summary: Return the current authenticated user's roles and permissions
      description: Return the current authenticated user's roles and permissions.
      operationId: getMyAccess
      tags:
        - Permissions
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userAccess'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/userAccess'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - access/read
      x-apiture-permission: getMyAccess
  /permissions:
    get:
      summary: Return a collection of API permissions
      description: >-
        Return a [paginated](https://developer.apiture.com/open/concepts/pagination), collection of all API permissions. The
        [links](https://developer.apiture.com/open/concepts/links) in the response include pagination links.
      operationId: getPermissions
      tags:
        - Permissions
      parameters:
        - name: start
          in: query
          description: The zero-based index of the first permission item to include in this page. The default 0 denotes the beginning of the collection.
          schema:
            type: integer
            format: int64
            default: 0
        - name: limit
          in: query
          description: The maximum number of permission representations to return in this page.
          schema:
            type: integer
            format: int32
            default: 100
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permissions'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/permissions'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - access/read
      x-apiture-permission: getPermissions
  /permissions/{permissionName}:
    parameters:
      - $ref: '#/components/parameters/permissionNamePathParam'
    get:
      summary: Fetch a representation of this permission
      description: Return a [HAL](https://developer.apiture.com/open/concepts/hal) representation of this permission resource.
      operationId: getPermission
      tags:
        - Permissions
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/permission'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this
                permission resource.
              schema:
                type: string
        '304':
          $ref: '#/components/responses/304'
        '404':
          $ref: '#/components/responses/404Permission'
      security:
        - apiKey: []
          accessToken:
            - access/read
      x-apiture-permission: getPermission
  /roles:
    get:
      summary: Return a collection of roles
      description: |-
        Return a
        [filterable](https://developer.apiture.com/open/concepts/filtering)
        collection of roles.
      operationId: getRoles
      parameters:
        - name: filter
          in: query
          description: >-
            Optional filter criteria. See [filtering](https://developer.apiture.com/open/concepts/filtering).<br>This collection may be filtered by the following properties and
            functions:<br>&bullet;  Property `categoryName` using functions `eq`,  `ne`,  `in`<br>&bullet;  Property `assignable` using functions `eq`,  `ne`<br>&bullet;  Property
            `user` using functions `eq`,  `ne`,  `in`<br>&bullet;  Property `updatedAt` using functions `eq`,  `ne`,  `in`,  `lt`,  `le`,  `gt`,  `ge`<br>&bullet;  Property
            `createdAt` using functions `eq`,  `ne`,  `in`,  `lt`,  `le`,  `gt`,  `ge`.
          schema:
            type: string
        - name: permission
          in: query
          schema:
            type: string
          description: Return a list of roles which contain the named permission. This does not include effective permissions which the role inherits from child roles.
        - name: category
          in: query
          description: Return a list of roles for the named category.
          schema:
            type: string
            enum:
              - system
              - operator
              - customer
        - name: assignable
          in: query
          description: Include only roles whose `assignable` property matches.
          schema:
            type: boolean
      x-apiture-traits:
        itemSchema: role
        filters:
          categoryName:
            filter:
              - eq
              - ne
              - in
          assignable:
            filter:
              - eq
              - ne
          user:
            filter:
              - eq
              - ne
              - in
          updatedAt:
            filter:
              - eq
              - ne
              - in
              - lt
              - le
              - gt
              - ge
          createdAt:
            filter:
              - eq
              - ne
              - in
              - lt
              - le
              - gt
              - ge
      tags:
        - Roles
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/roles'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/roles'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - access/read
      x-apiture-permission: getRoles
  /roles/{role}:
    parameters:
      - $ref: '#/components/parameters/rolePathParam'
    get:
      summary: Fetch a representation of this role
      description: >-
        Return a [HAL](https://developer.apiture.com/open/concepts/hal) representation of this role resource. Note that if looking up a role by name, the response will be a (301)
        redirect to the role resource by `_id`.
      operationId: getRole
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
        - name: embed
          in: query
          description: >-
            A pipe-delimited list of properties to include in the returned role's `_embedded` objects. List items must be (`roles`, `permissions`, `effectivePermissions` property
            names of the [`roleEmbedded`](#schema-roleEmbedded) model schema.
          style: pipeDelimited
          schema:
            type: array
            items:
              type: string
              enum:
                - roles
                - permissions
                - effectivePermissions
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/role'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/role'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this role
                resource.
              schema:
                type: string
        '301':
          description: Moved. The resource was found by role name, but the service redirects the client to the role resource by ID via the `Location` response header.
          headers:
            Location:
              description: The canonical URI of the role resource.
              schema:
                type: string
                format: uri
        '304':
          $ref: '#/components/responses/304'
        '404':
          $ref: '#/components/responses/404Role'
      security:
        - apiKey: []
          accessToken:
            - access/read
      x-apiture-permission: getRole
  /:
    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
      responses:
        '200':
          description: OK.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/root'
            application/json:
              schema:
                $ref: '#/components/schemas/root'
      tags:
        - API
      security:
        - apiKey: []
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
            application/vnd.oai.openapi+json;version=3.0:
              schema:
                type: object
            application/vnd.oai.openapi;version=3.0:
              schema:
                type: object
      tags:
        - API
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: API-Key
      in: header
      description: API Key based authentication. See details at [Secure Access](https://developer.apiture.com/open/secure-access).
    accessToken:
      type: oauth2
      description: OAuth2 client access token authentication. See details at [Secure Access](https://developer.apiture.com/open/secure-access).
      flows:
        authorizationCode:
          authorizationUrl: https://auth.apiture.com/oauth2/authorize
          tokenUrl: https://auth.apiture.com/auth/oauth2/token
          refreshUrl: https://auth.apiture.com/auth/oauth2/token
          scopes:
            access/read: Read access to roles and permissions.
  parameters:
    permissionNamePathParam:
      name: permissionName
      description: The unique name of a permission. This corresponds to the permission's `name` property.
      in: path
      schema:
        type: string
      required: true
    filterQueryParam:
      name: filter
      in: query
      description: Optional filter criteria. See [filtering](https://developer.apiture.com/open/concepts/filtering).
      schema:
        type: string
    rolePathParam:
      name: role
      description: The unique `name` or `_id` (identifier) of a role.
      in: path
      schema:
        type: string
      required: true
    ifMatchHeaderParam:
      name: If-Match
      description: The entity tag that was returned in the `ETag` response. If passed, this must match the current entity tag of the resource.
      in: header
      schema:
        type: string
    ifNoneMatchHeaderParam:
      name: If-None-Match
      description: >-
        The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` returns 304 (Not Modified) and no response body, else the
        resource representation is returned.
      in: header
      schema:
        type: string
  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 contains details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '412':
      description: Precondition Failed. The supplied `If-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '422':
      description: >-
        Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid. The `_error` field in the response contains details about the request
        error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    404Permission:
      description: Not Found. There is no such permission resource at the specified `{permissionName}`. The `_error` field in the response contains details about the request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    404Role:
      description: Not Found. There is no such role resource at the specified `{role}`. The `_error` field in the response contains details about the request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    204Deleted:
      description: No Content. The resource was deleted successfully.
  schemas:
    permissionFields:
      x-apiture-fragment: true
      title: Permission Fields (v1.0.0)
      description: Common fields of the permission resource used to build other model schemas.
      x-apiture-todo: In a future release of this API, we will define a `createPermission` schema which will also use this schema.
      properties:
        name:
          description: The name of this permission. This immutable programmatic identifier also acts as the permission's unique `{permissionName}`.
          type: string
          pattern: ^[a-z][a-zA-Z0-9]{0,63}$
          maxLength: 64
          minLength: 6
          example: createScheduledTransfer
        label:
          description: A short text label for this permission, for use in human presentation. This field may be localized.
          type: string
          maxLength: 128
          minLength: 1
          example: Create a new scheduled transfer request
      example:
        name: createScheduledTransfer
        description: Create a new scheduled transfer in the `scheduledTransfers` collection.
      x-apiture-version: 1.0.0
    summaryPermission:
      title: Permission Summary (v1.0.0)
      description: >
        Summary representation of a permission resource in the permissions collection. A permission represents an allowed API operation. This representation normally does not
        contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get the full permission object.



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


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

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


        <table>

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


        <tr>

        <td><a href='#op-getPermission'><strong><code>self</code></strong></a></td><td>Fetch a representation of this permission</td><td><code>GET</code></td>

        </tr>

        </table>
      allOf:
        - $ref: '#/components/schemas/abstractResource'
        - $ref: '#/components/schemas/permissionFields'
      x-apiture-links:
        - rel: self
          operationId: getPermission
      example:
        name: createScheduledTransfer
        label: Create a new scheduled transfer request
        _profile: https://production.api.apiture.com/schemas/access/summaryPermission/v1.0.0/profile.json
        _links:
          self:
            href: https://api.devbank.apiture.com/access/permissions/createScheduledTransfer
      x-apiture-version: 1.0.0
    permission:
      title: Permission (v1.0.0)
      description: |
        Representation of permission resources. A permission represents an allowed API operation. Permissions are aggregated into roles.


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

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

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

        <tr>
        <td><a href='#op-getPermission'><strong><code>self</code></strong></a></td><td>Fetch a representation of this permission</td><td><code>GET</code></td>
        </tr>

        <tr>
        <td><a href='#op-getRoles'><strong><code>apiture:roles</code></strong></a></td><td>List roles which have this permission (directly)</td><td><code>GET</code></td>
        </tr>
        </table>
      allOf:
        - $ref: '#/components/schemas/summaryPermission'
        - type: object
          properties:
            description:
              description: A more detailed description of this permission.
              type: string
              format: markdown
              maxLength: 512
              example: Create a new scheduled transfer in the `scheduledTransfers` collection.
      x-apiture-links:
        - rel: self
          operationId: getPermission
        - rel: apiture:roles
          operationId: getRoles
          title: List roles which have this permission (directly)
      example:
        name: createScheduledTransfer
        label: Create a new scheduled transfer request
        description: Adds either a new one-time or a recurring transfer, to transfer funds between internal accounts or between an internal and a verified external account.
        _profile: https://production.api.apiture.com/schemas/access/permission/v1.0.0/profile.json
        _links:
          self:
            href: https://api.devbank.apiture.com/access/permissions/createScheduledTransfer
          apiture:roles:
            href: https://api.devbank.apiture.com/access/roles?permission=createScheduledTransfer
        _embedded: {}
      x-apiture-version: 1.0.0
    permissionsEmbedded:
      title: Permissions Embedded Objects (v1.0.0)
      description: Objects embedded in the `permissions` schema.
      type: object
      properties:
        items:
          description: An array containing summary representations of permission items.
          type: array
          items:
            $ref: '#/components/schemas/summaryPermission'
      x-apiture-version: 1.0.0
    permissions:
      title: Permission Collection (v1.0.0)
      description: >-
        Collection of permissions. The items in the collection are ordered in the `_embedded.items` array; the collection `name` is `permissions`. The top-level `_links` object may
        contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
      allOf:
        - $ref: '#/components/schemas/collection'
        - type: object
          properties:
            _embedded:
              type: object
              description: Embedded objects.
              allOf:
                - $ref: '#/components/schemas/permissionsEmbedded'
      example:
        _profile: https://production.api.apiture.com/schemas/access/permissions/v1.0.0/profile.json
        name: permissions
        start: 10
        limit: 10
        count: 67
        _links:
          self:
            href: https://api.devbank.apiture.com/access/permissions?start=10&limit=10
          first:
            href: https://api.devbank.apiture.com/access/permissions?start=0&limit=10
          next:
            href: https://api.devbank.apiture.com/access/permissions?start=20&limit=10
          collection:
            href: https://api.devbank.apiture.com/access/permissions
        _embedded:
          items:
            - name: createScheduledTransfer
              _profile: https://production.api.apiture.com/schemas/access/summaryPermission/v1.0.0/profile.json
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/permissions/createScheduledTransfer
            - name: updatedScheduledTransfer
              _profile: https://production.api.apiture.com/schemas/access/summaryPermission/v1.0.0/profile.json
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/permissions/updatedScheduledTransfer
      x-apiture-version: 1.0.0
    roleCategory:
      title: Role Category (v1.0.0)
      description: |+
        The category of users that may be assigned this role.

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

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

        <tr>
            <td><strong><code>system</code></strong></td><td>System Administrative User: <p>System administrative users who manage the deployment.</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>operator</code></strong></td><td>Financial Institution Operator: <p>Administrator employees of the financial institution such as the deposits manager or the wire room staff, customer support, and so on These financial institution users use administrative and back office applications to manage the digital banking.</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>customer</code></strong></td><td>Banking Customer User: <p>Banking customers who hold accounts and use applications to perform digital banking. (Reserved for future use.)</p>
        </td>
            </tr>
        </table>

      type: string
      enum:
        - system
        - operator
        - customer
      x-apiture-enum: roleCategory
      x-apiture-version: 1.0.0
    roleFields:
      x-apiture-version: 1.1.0
      title: Role Fields (v1.1.0)
      description: Common fields of the role resource used to build other model schemas.
      x-apiture-fragment: true
      x-apiture-todo: In a future release of this API, we will define a `createRole` schema which will also use this schema.
      type: object
      properties:
        name:
          description: The name of this role. This immutable programmatic identifier also acts as the role's unique `{role}`.
          type: string
          maxLength: 64
          minLength: 6
          example: moveMoney
          pattern: ^[a-z][a-zA-Z0-9]{0,63}$
        label:
          description: The text label for this role, for use in human presentation. This field may be localized.
          type: string
          maxLength: 128
          minLength: 1
          example: Move Money
        categoryName:
          description: |
            The category of users that may be assigned this role. Child roles are constrained:
              * a `customer` role can only have `customer` child roles.
              * a `operator` role can only have `customer` or `operator` child roles.
              * a `system` role can have any child roles.
          allOf:
            - $ref: '#/components/schemas/roleCategory'
        assignable:
          description: If `true`, this role can be assigned to users. If false, the role is used for composing other roles only.
          type: boolean
          default: false
      example:
        name: moveMoney
        label: Move Money
        description: Create, modify, and cancel transfers, payments, checks, and other funds movement.
        categoryName: customer
        assignable: true
    summaryRole:
      x-apiture-version: 1.1.0
      title: Role Summary (v1.1.0)
      description: >
        Summary representation of a role resource in the roles collection. This representation normally does not contain any `_embedded` objects. If needed, call the `GET`
        operation on the item's `self` link to get full role object.



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


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

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


        <table>

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


        <tr>

        <td><a href='#op-getRole'><strong><code>self</code></strong></a></td><td>Fetch a representation of this role</td><td><code>GET</code></td>

        </tr>

        </table>
      allOf:
        - $ref: '#/components/schemas/abstractResource'
        - $ref: '#/components/schemas/roleFields'
        - type: object
          properties:
            _id:
              description: The unique identifier for this role. This is an immutable opaque string. This is the `{role}` in canonical resource URIs.
              readOnly: true
              type: string
              maxLength: 64
      x-apiture-links:
        - rel: self
          operationId: getRole
      example:
        _id: 7655fcde-c3a4-404e-a662-9beede86bfa9
        name: moveMoney
        label: Move Money
        assignable: true
        categoryName: customer
        _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
        _links:
          self:
            href: https://api.devbank.apiture.com/access/roles/7655fcde-c3a4-404e-a662-9beede86bfa9
    roleEmbedded:
      x-apiture-version: 1.1.0
      title: Role Embedded Objects (v1.1.0)
      description: Objects embedded in a `role` object.
      type: object
      properties:
        roles:
          description: >-
            An array of direct child roles. This is included in a role representation if the `embed` query parameter on the [`getRole`](#op-getRole) operation includes the name,
            `roles`.
          type: array
          items:
            $ref: '#/components/schemas/summaryRole'
        permissions:
          description: >-
            An array containing permission objects for all the direct permissions in this role. This is included in a role representation if the `embed` query parameter on the
            [`getRole`](#op-getRole) operation includes the name, `permissions`.
          type: array
          items:
            $ref: '#/components/schemas/summaryPermission'
        effectivePermissions:
          description: >-
            An array containing all the effective permission names for this role. This is the union of the direct permissions for the role and all the effective permissions of all
            the role's direct child roles. This is included in a role representation if the `embed` query parameter on the [`getRole`](#op-getRole) operation includes the name,
            `effectivePermissions`.
          type: array
          items:
            type: string
      example:
        roles:
          - _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
            _id: 0d3a9972-a843-458a-b6a9-dec3feb458ff
            name: transfers
            categoryName: customer
            label: Create and Manage Transfers
            _links:
              self:
                href: https://api.devbank.apiture.com/access/roles/0d3a9972-a843-458a-b6a9-dec3feb458ff
          - _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
            _id: 93959e3d-f61d-452f-8054-73a92cdfe263
            name: payBills
            categoryName: customer
            label: Create and Manage Bill Payments
            _links:
              self:
                href: https://api.devbank.apiture.com/access/roles/93959e3d-f61d-452f-8054-73a92cdfe263
        permissions:
          - _profile: https://production.api.apiture.com/schemas/access/permission/v1.0.0/profile.json
            name: getScheduledTransfer
            label: View a scheduled transfer
            _links:
              self:
                href: https://api.devbank.apiture.com/access/permissions/getScheduledTransfer
          - _profile: https://production.api.apiture.com/schemas/access/permission/v1.0.0/profile.json
            name: getScheduledTransfers
            label: View all scheduled transfers
            _links:
              self:
                href: https://api.devbank.apiture.com/access/permissions/getScheduledTransfers
        effectivePermissions:
          - getScheduledTransfer
          - getScheduledTransfers
          - createScheduledTransfer
          - cancelScheduledTransfer
          - updateScheduledTransfer
          - deleteScheduledTransfer
          - getPaymentInstruction
          - getPaymentInstructions
          - createPaymentInstruction
          - submitPaymentInstruction
          - cancelPaymentInstruction
          - deletePaymentInstruction
    roleReference:
      title: Role Reference (v1.0.0)
      description: A reference to a role resource.
      type: object
      required:
        - _id
        - name
      properties:
        _id:
          description: The unique identifier for the role.
          readOnly: true
          type: string
          maxLength: 64
        name:
          description: The name of this role.
          type: string
          maxLength: 64
          minLength: 6
          example: moveMoney
          pattern: ^[a-z][a-zA-Z0-9]{0,63}$
        label:
          description: The text label for this role.
          type: string
          maxLength: 128
          minLength: 1
          example: Move Money
        uri:
          description: The URI of the role's resource.
          type: string
          format: uri
          example: https://api.devbank.apiture.com/access/roles/78c16684-0628-4363-a557-987839245d2c
      example:
        _id: 78c16684-0628-4363-a557-987839245d2c
        name: approveApproval
        uri: https://api.devbank.apiture.com/access/roles/78c16684-0628-4363-a557-987839245d2c
      x-apiture-version: 1.0.0
    permissionReference:
      title: Permission Reference (v1.0.0)
      description: A reference to a permission resource.
      required:
        - name
      properties:
        name:
          description: The name of this permission.
          type: string
          maxLength: 64
          minLength: 6
          example: moveMoney
          pattern: ^[a-z][a-zA-Z0-9]{0,63}$
        uri:
          description: The URI of the permission's resource.
          type: string
          format: uri
          example: https://api.devbank.apiture.com/access/permissions/moveMoney
      example:
        name: approveApproval
        uri: https://api.devbank.apiture.com/access/permissions/approveApproval
      x-apiture-version: 1.0.0
    userAccess:
      x-apiture-version: 1.1.0
      title: User Access (v1.1.0)
      description: >-
        The lists of the currently authenticated user's access: their assigned roles, any effective roles inherited from those assigned role's, and the full set of effective
        permissions associated with those roles.
      required:
        - roles
        - effectiveRoles
        - effectivePermissions
      allOf:
        - $ref: '#/components/schemas/abstractResource'
        - type: object
          properties:
            roles:
              description: All the roles assigned directly to a user.
              type: array
              items:
                $ref: '#/components/schemas/summaryRole'
            effectiveRoles:
              description: The union of the user's assigned roles and the roles which have the assigned roles as an ancestor.
              type: array
              items:
                $ref: '#/components/schemas/roleReference'
            effectivePermissions:
              description: An array containing all the effective permission names associated with all the roles that are assigned to the user.
              type: array
              items:
                type: string
      example:
        _profile: https://production.api.apiture.com/schemas/access/userAccess/v1.1.0/profile.json
        roles:
          - _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
            _id: 0d3a9972-a843-458a-b6a9-dec3feb458ff
            name: transfers
            categoryName: customer
            label: Create and Manage Transfers
            _links:
              self:
                href: https://api.devbank.apiture.com/access/roles/0d3a9972-a843-458a-b6a9-dec3feb458ff
          - _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
            _id: 93959e3d-f61d-452f-8054-73a92cdfe263
            name: payBills
            categoryName: customer
            label: Create and Manage Bill Payments
            _links:
              self:
                href: https://api.devbank.apiture.com/access/roles/93959e3d-f61d-452f-8054-73a92cdfe263
        effectiveRoles:
          - _id: 0d3a9972-a843-458a-b6a9-dec3feb458ff
            name: transfers
            uri: https://api.devbank.apiture.com/access/roles/0d3a9972-a843-458a-b6a9-dec3feb458ff
          - _id: 93959e3d-f61d-452f-8054-73a92cdfe263
            name: payBills
            uri: https://api.devbank.apiture.com/access/roles/93959e3d-f61d-452f-8054-73a92cdfe263
        effectivePermissions:
          - getScheduledTransfer
          - getScheduledTransfers
          - createScheduledTransfer
          - cancelScheduledTransfer
          - updateScheduledTransfer
          - deleteScheduledTransfer
          - getPaymentInstruction
          - getPaymentInstructions
          - createPaymentInstruction
          - submitPaymentInstruction
          - cancelPaymentInstruction
          - deletePaymentInstruction
    role:
      x-apiture-version: 1.1.0
      title: Role (v1.1.0)
      description: >
        Representation of _role_ resources. A role is an aggregation of [permissions](#schema-permission) or other roles. Users may be assigned one or more roles (although role
        assignment is outside the scope of this API.) Note that, while role's may be [accessed by `name` or `_id`](#op-getRole), the `self` link always uses the canonical form,
        `_id`.



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


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

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


        <table>

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


        <tr>

        <td><a href='#op-getRole'><strong><code>self</code></strong></a></td><td>Fetch a representation of this role</td><td><code>GET</code></td>

        </tr>

        </table>
      allOf:
        - $ref: '#/components/schemas/summaryRole'
        - type: object
          properties:
            description:
              description: The role's description.
              type: string
              format: markdown
              maxLength: 512
              example: 'Create, modify, or cancel money movements: transfers, payments, etc.'
            roles:
              description: Child roles that this role inherits permissions from. This may be an empty array.
              type: array
              items:
                $ref: '#/components/schemas/roleReference'
              x-apiture-todo: Confirm if this maxLength is OK -- not too small
              maxLength: 256
            permission:
              description: Direct permissions granted by this role. This may be an empty array.
              type: array
              items:
                $ref: '#/components/schemas/permissionReference'
              x-apiture-todo: Confirm if this maxLength is OK -- not too small
              maxLength: 2048
            createdAt:
              description: >-
                The date-time when the role was created, in `YYYY-MM-DDThh:mm:ss.sssZ` [RFC 3339](https://tools.ietf.org/html/rfc3339) `date-time` format, UTC. This is derived and
                immutable.
              type: string
              format: date-time
              readOnly: true
            updatedAt:
              description: >-
                The date-time when the role was last updated, in `YYYY-MM-DDThh:mm:ss.sssZ` [RFC 3339](https://tools.ietf.org/html/rfc3339) `date-time` format, UTC. This is derived
                and immutable.
              type: string
              format: date-time
              readOnly: true
            _embedded:
              description: Optional related objects (child roles, direct permissions, effective permissions) embedded in a role representation.
              allOf:
                - $ref: '#/components/schemas/roleEmbedded'
      x-apiture-links:
        - rel: self
          operationId: getRole
      example:
        _id: 7655fcde-c3a4-404e-a662-9beede86bfa9
        name: moveMoney
        label: Move Money
        assignable: true
        description: Create, modify, and cancel transfers, payments, checks, and other funds movement.
        categoryName: customer
        createdAt: '2021-01-25T12:46:06.375Z'
        roles:
          - _id: 0d3a9972-a843-458a-b6a9-dec3feb458ff
            name: transfers
            uri: https://api.devbank.apiture.com/access/roles/0d3a9972-a843-458a-b6a9-dec3feb458ff
          - _id: 93959e3d-f61d-452f-8054-73a92cdfe263
            name: payBills
            uri: https://api.devbank.apiture.com/access/roles/93959e3d-f61d-452f-8054-73a92cdfe263
        permissions:
          - name: getScheduledTransfer
            uri: https://api.devbank.apiture.com/access/permissions/getScheduledTransfer
          - name: getScheduledTransfers
            uri: https://api.devbank.apiture.com/access/permissions/getScheduledTransfers
        _profile: https://production.api.apiture.com/schemas/access/role/v1.1.0/profile.json
        _links:
          self:
            href: https://api.devbank.apiture.com/access/roles/7655fcde-c3a4-404e-a662-9beede86bfa9
          apiture:permissions:
            href: https://api.devbank.apiture.com/access/permissions?role=7655fcde-c3a4-404e-a662-9beede86bfa9
        _embedded:
          roles:
            - _profile: https://production.api.apiture.com/schemas/access/role/v1.1.0/profile.json
              _id: 0d3a9972-a843-458a-b6a9-dec3feb458ff
              name: transfers
              categoryName: customer
              label: Create and Manage Transfers
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/roles/0d3a9972-a843-458a-b6a9-dec3feb458ff
            - _id: 93959e3d-f61d-452f-8054-73a92cdfe263
              name: payBills
              categoryName: customer
              label: Create and Manage Bill Payments
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/roles/93959e3d-f61d-452f-8054-73a92cdfe263
          permissions:
            - _profile: https://production.api.apiture.com/schemas/access/permission/v1.0.0/profile.json
              name: getScheduledTransfer
              label: View a scheduled transfer
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/permissions/getScheduledTransfer
            - _profile: https://production.api.apiture.com/schemas/access/permission/v1.0.0/profile.json
              name: getScheduledTransfers
              label: View all scheduled transfers
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/permissions/getScheduledTransfers
          effectivePermissions:
            - getScheduledTransfer
            - getScheduledTransfers
            - createScheduledTransfer
            - cancelScheduledTransfer
            - updateScheduledTransfer
            - deleteScheduledTransfer
            - getPaymentInstruction
            - getPaymentInstructions
            - createPaymentInstruction
            - submitPaymentInstruction
            - cancelPaymentInstruction
            - deletePaymentInstruction
    rolesEmbedded:
      x-apiture-version: 1.1.0
      title: Roles Embedded Objects (v1.1.0)
      description: Objects embedded in the `roles` collection.
      type: object
      properties:
        items:
          description: An array containing role items.
          type: array
          items:
            $ref: '#/components/schemas/summaryRole'
    roles:
      x-apiture-version: 1.1.0
      title: Role Collection (v1.1.0)
      description: Collection of roles. The items in the collection are listed in the `_embedded.items` array; the collection `name` is `roles`.
      allOf:
        - $ref: '#/components/schemas/collection'
        - type: object
          properties:
            _embedded:
              description: roles collection items
              allOf:
                - $ref: '#/components/schemas/rolesEmbedded'
      example:
        _profile: https://production.api.apiture.com/schemas/access/roles/v1.1.0/profile.json
        name: roles
        start: 0
        limit: 100
        count: 7
        _links:
          self:
            href: https://api.devbank.apiture.com/access/roles?start=00&limit=100
          collection:
            href: https://api.devbank.apiture.com/access/roles
        _embedded:
          items:
            - name: role1
              _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/roles/99ade01a-e676-456c-a546-e2fd003c834b
            - name: role2
              _profile: https://production.api.apiture.com/schemas/access/summaryRole/v1.1.0/profile.json
              _links:
                self:
                  href: https://api.devbank.apiture.com/access/roles/70cd5898-3e74-4fcf-917c-b14030a4a061
    root:
      x-apiture-version: 2.1.0
      title: API Root (v2.1.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.1.0/model.json).
      example:
        id: apiName
        name: API name
        apiVersion: 1.0.0
        _profile: https://production.api.apiture.com/schemas/common/root/v2.1.0/profile.json
        _links: {}
      allOf:
        - $ref: '#/components/schemas/abstractResource'
        - type: object
          properties:
            _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.
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/root/v2.1.0/model.json
      x-apiture-namespace: common
    errorResponse:
      x-apiture-version: 2.1.0
      title: Error Response (v2.1.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.1.0/model.json).
      allOf:
        - $ref: '#/components/schemas/abstractResource'
      example:
        _profile: https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/profile.json
        _error:
          _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
          message: Description of the error will appear here.
          statusCode: 422
          type: specificErrorType
          attributes:
            value: Optional attribute describing the error
          remediation: Optional instructions to remediate the error may appear here.
          occurredAt: '2018-01-25T05:50:52.375Z'
          _links:
            describedby:
              href: https://production.api.apiture.com/errors/specificErrorType
          _embedded:
            errors: []
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/errorResponse/v2.1.0/model.json
      x-apiture-namespace: common
    abstractResource:
      x-apiture-version: 2.1.0
      title: Abstract Resource (v2.1.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.1.0/model.json).
      allOf:
        - $ref: '#/components/schemas/abstractRequest'
        - type: object
          properties:
            _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'
              readOnly: true
      example:
        _profile: https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/profile.json
        _links:
          self:
            href: https://api.devbank.apiture.com/apiName/resourceName/resourceId
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/abstractResource/v2.1.0/model.json
      x-apiture-namespace: common
    collection:
      x-apiture-version: 2.1.0
      title: Collection (v2.1.0)
      description: |-
        A collection of resources. This is an abstract model schema which is extended to define specific resource collections.

        This schema was resolved from [`common/collection`](https://production.api.apiture.com/schemas/common/collection/v2.1.0/model.json).
      allOf:
        - $ref: '#/components/schemas/abstractResource'
        - type: object
          properties:
            count:
              description: >-
                The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the
                collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter.
              type: integer
            start:
              description: The start index of this page of items.
              type: integer
            limit:
              description: The maximum number of items per page.
              type: integer
            name:
              description: The name of the collection.
              type: string
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/collection/v2.1.0/model.json
      x-apiture-namespace: common
    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:
          $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/open/concepts/profiles/) which describes the representation.
          type: string
          format: uri
          readOnly: true
      example:
        _profile: https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json
        _links: {}
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json
      x-apiture-namespace: common
    error:
      x-apiture-version: 2.1.0
      title: Error (v2.1.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.1.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.1.0/model.json
      x-apiture-namespace: common
    attributes:
      x-apiture-version: 2.1.0
      title: Attributes (v2.1.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.1.0/model.json).
      type: object
      additionalProperties: true
      x-apiture-resolved-from: https://production.api.apiture.com/schemas/common/attributes/v2.1.0/model.json
      x-apiture-namespace: common
    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
    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/open/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
x-apiture-traits:
  - api:
      title: Access
      basePath: access
      applied: true
      links:
        - getApi
        - getApiDoc
        - getRoles
        - getPermissions
  - resource:
      name: role
      description: Describes a role (assignable to users), composed of one or more permissions.
      immutable: true
      sortable: false
      searchable: false
      filterable: true
      paginated: false
      applied: true
  - resource:
      name: permission
      description: Describes a permission or grant to perform an API operation.
      immutable: true
      sortable: false
      searchable: false
      applied: true
  - security:
      baseScope: access
      applied: true
x-apiture-annotated-at: '2023-08-24T13:34:13.285Z'
