swagger: '2.0'
info:
  title: Auth
  description: >

    The Authentication API is an identity layer based on OpenID Connect (OIDC) and OAuth 2.0. Accessing resources in the Apiture Open platform
    requires registering an OAuth consumer before making authenticated API requests.

    ## Discovery

    The OpenID Connect Discovery metadata can be retrieved by browsing to the `/auth/openid/metadata` URL. The metadata information is public.

    ## Creating a client

    Request an OAuth client key and secret by visiting [developer.apiture.com](https://developer.apiture.com), registering your partner organization,
    defining a new client application, and requesting API keys for that application and a target environment.

    After submitting the request, Apiture will provision the API keys and the client ID and client secret which allow the client's user to
    authenticate and request authentication tokens at run time; these authentication tokens and the API key are used to authenticate each API request.
    See [Secure Access](https://developer.apiture.com/docs/secure-access) for further details.

    ## Open ID Connect and OAuth 2.0 Authentication

    The Authentication API supports OpenID Connect authentication flows and OAuth 2.0:

      - Authorization Code Flow (OpenID Connect), for Mobile Applications or Web Applications or apps where a user logs in
      - Client Credentials Grant (OAuth 2.0), for back-end service applications in a secure environment

    More information about using these flows are in the [`authorize`](#op-authorize) and [`getToken`](#op-getToken) operations below.

    ### OpenID Connect Authorization Code Flow

    This interactive flow involves browser redirection to the Apiture Identity Provider URL (the OAuth _authorization server_) for secure user login
    and consent. After the first redirection, the user is redirected back to the requesting application using the callback URL associated with the
    client application in the [developer portal](https://developer.apiture.com).

      1. The client requests user authentication via the [`authorize`](#op-authorize) operation, passing a unique random `state` value
      1. The user authenticates by entering their credentials in the authorization server's form
      1. The user may also be prompted to give consent to specific application access
      1. If the client request and user authentication are valid, the authorization operation return a 302 response and `Location` header with the client redirect URI, a `code`, and the client `state` value
      1. The client redirects to the redirect URI in order to process the response and code. The request handler should ensure the `state` matches the one passed in step #1.
      1. If the `state` matches, the client exchanges the code for tokens via the [`getToken`](#op-getToken) operation to complete the flow

    See [Secure Access](https://developer.apiture.com/docs/secure-access) for further details.

    ### OAuth 2.0 Client Credentials Grant

    With this authentication method, the client [requests an authentication token](#op-getToken) passing the client ID and client secret that have
    been provisioned by the [developer portal](https://developer.apiture.com). Theis method does not use user authentication or credentials; hence the
    access token is not associated with a financial institution customer. This is _only_ suitable for **secure applications**, such as those in a
    financial institution's data center. Web or mobile applications must not use this method.


    See [Secure Access](https://developer.apiture.com/docs/secure-access) for further details.

    ## Password reset flow

    It is possible to reset the user's password from an unauthenticated space by sending the user's key identifying information.

      1. Start the process by issuing a [`POST` to `/passwordResetRequests`](#op-passwordResetRequest) with the user's username, taxId
      and birthdate. A confirmation code is sent via the preconfigured delivery channel as a result
      of this operation.
      2. Use the confirmation code as part of a [`POST` request to `/passwordResets`](#op-passwordReset) along with the
      user's username and the new desired password. A successful password reset will be acknowledged
      with a 202 status code.

    ## Changing the user's password

    To change a user's password, an already authenticated user should [`POST` to `/my/password`[#op-changeUserPassword). The client should encrypt the
    old and new password using client side encryption obtained from the [`GET /encryptionKeys`]{#op-getEncryptionKeys).

    ## Using the Tokens

    Upon successful authentication via the [`authorize`](#op-authorize) operation, use the [`getToken`](#op-getToken) operation to obtain a
    [`oauthToken`](#schema-oauthToken) response containing an `access_token` that can be used to call secured API endpoints. Each request to a secured
    endpoint must include the access token (also known a bearer token) as part of the `Authorization` header: `Authorization: Bearer {access_token}`.


    The access token has an expiration time in milliseconds in the `expires_in` property in the response, and the the refresh token is in the the
    `refresh_token` property. To refresh an expiring or expired access tokenm, use the [`/oauth2/token#getToken`](#op-getToken) endpoint with the
    `grant_type` query parameter set to `refresh_token`, and the `refresh_token` query parameter set to the `refresh_token` obtained when the token
    was first issued.

    ## Devices

    For additional security, this API also manages the devices (such as cell phones, tablets, computers) that the user uses for digital banking. This
    allows the Apiture platform to notify the user if someone logs onto their account from an unknown device. Each device has a unique device ID.


    Device management improves the multi-factor authentication (MFA) experience for users. If SMS-based MFA is enabled, end users must input a
    security code received via SMS in addition to entering their password during every sign-in . With device management, users can specify that a
    device is trusted and the authentication service will remember the device as trusted. Trusted devices can serve as a second factor of
    authentication instead of requiring a security code delivered via SMS.


    This feature tracks each device/user combination separately, such as a husband and wife logging onto digital banking on a shared laptop or table.
    If the husband has chosen to trust the device, he may sign in using the device and not have to use secondary authentication such as an code sent
    via SMS. If the wife has not marked the device as trusted, when they sign in, they will need to use the secondary authentication such as an code
    sent via SMS.


    A financial institution can disable tracking of trusted devices so that other secondary authentication such as SMS codes or biometrics must be
    used on each sign in.

    ## Identity Challenges

    The Challenges and Authenticator operations support additional user identity verification challenges to allow a user to verify they are who they
    claim to be, such as entering a code send via email or SMS. A challenge represents a resource for tracking this additional authentication.


    For example, in the Users API, when a user tries to change their preferred mailing address, email address, or phone number, the operations may
    require an additional identity verification challenge. This helps prevent fraudulent use if someone gains access to an account and attempts to
    take it over without the owner's consent or knowledge by changing the account's contact information. Other APIs which may use the Challenge API
    include the Transfers API to confirm identity before transferring money higher than some user-level transfer threshold or much higher than
    historical transfers, or the Accounts API when adding or removing joint owners or authorized signers.


    API services initiate challenges when required. If an operation requires a challenge, the initial operation fails with a 401 Unauthorized response
    with an `_error` object in the response. That [error response](http://developer.apiture.com/docs/concepts/errors) has the error type of
    `identityChallengeRequired`. The error object contains a `_embedded.challenge` object which describes the challenge (see the
    `challengeErrorResponse` schema).


    A challenge consists of:

      * a `contextUri` - the URI of a resource which the challenge is requested (such as the Transfers API,
      or the Accounts API), a set of authentication types)
      * an array of `authenticators` which the end user can select from
      in order to verify their identity
      * a `reason` that the service is requesting additional authentication
      * the `userId` of the user who is being challenged
      * `createdAt`, `verifiedAt`, and `failedAt`, and `redeemedAt` timestamps.
      * the `state` of the challenge
      * other data for limiting and tracking redemption (use) of a challenge


    An authenticator contains
      * the authentication `type` such as `sms` or `email`
      * the authentication category such as `knowledge`, `biometric`, `device`
      * additional authentication details in `attributes`
      * a link to a JSON schema that describes the attributes
      * a link to the challenge to which it relates
      * `createdAt`, `verifiedAt`, and `failedAt` timestamps
      * `maximumRetries` limits how many times an authenticator may be retried


    For example, a `type` may be `sms` which means the authenticator will send an SMS message to the user's mobile device; the message contains a code
    (4 to 6 digits) which the user must enter in the application. The schema attached to `sms` will list the preferred mobile device number(s) for the
    user or account, and perhaps other allowed mobile device phone numbers. Other types include `email` (a similar code is sent to the user at the
    preferred email address.) Clients must be prepared to handle all the authenticator types.


    The client should start the selected authenticators by using a `POST` to their `apiture:start` links (operation
    [`startAuthenticator`](#op-startAuthenticator). For example, for `sms` and `email` authenticator types, the service will send a code to the user's
    preferred mobile phone number or email address respectively. The `type` in the authenticator includes a JSON schema which describes the data that
    should be passed in the authenticator's `attributes`. The client should collect data from the user and then post the authenticator resource (with
    the user data in the `attributes`) to the `verifyAuthenticator` operation. This validates the data and either completes the authenticator (and
    challenge) or fails.


    After the required authenticators are verified and the challenge has been completed, the client application should retry the initial operation
    that failed with the 401 error. The client should pass the `_id` of the challenge resource in the `Apiture-Challenge` request header on this
    operation retry. Operations which participate in the Challenge protocol will document the optional `Apiture-Challenge` request header as one of
    the operation's parameters.


    Challenges and authenticators expire and they are automatically deleted after a delay of several minutes.

    ## Session Tracking

    You may use the Authentication API to track user sessions. There are operations to mark the beginning, continuation, and ending of a user session
    (log on, refresh a user's access token, log off). See the `startUserSession`, `continueUserSession`, `endUserSession` operations.


    # 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.




    ## <span class='errorType' id="err-accountAlreadyConfirmed">accountAlreadyConfirmed</span>


    **Description**: A user has already confirmed this login account. <br>

    **Remediation**: Your login account is ready for use. You can login or use the Forgot Password option if you have forgotten your username.



    ## <span class='errorType' id="err-getTokenAccessDenied">getTokenAccessDenied</span>


    **Description**: The client is not authorized to generate this token. <br>

    **Remediation**: Make sure the client credentials are valid.



    ## <span class='errorType' id="err-invalidGrant">invalidGrant</span>


    **Description**: The provided code is not valid. <br>

    **Remediation**: Check the provided code.



    ## <span class='errorType' id="err-postTokenAccessDenied">postTokenAccessDenied</span>


    **Description**: The client is not authorized to generate this token. <br>

    **Remediation**: Make sure the client is authorized.



    ## <span class='errorType' id="err-invalidSymbolForNonEmailUsernameFormat">invalidSymbolForNonEmailUsernameFormat</span>


    **Description**: Username cannot contain the ‘@’ symbol. <br>

    **Remediation**: Choose a new username without the ‘@’ symbol.



    ## <span class='errorType' id="err-usernameRequestConflict">usernameRequestConflict</span>


    **Description**: There was a conflict requesting the username. <br>

    **Remediation**: Make sure the supplied information is correct.



    ## <span class='errorType' id="err-invalidUsernameRequest">invalidUsernameRequest</span>


    **Description**: The username request was not processed. <br>

    **Remediation**: Check that the user exists and that the attributes match the request.



    ## <span class='errorType' id="err-invalidNewPassword">invalidNewPassword</span>


    **Description**: The new password is not valid. <br>

    **Remediation**: Check that the new password conforms to password policy.



    ## <span class='errorType' id="err-dataNotEncrypted">dataNotEncrypted</span>


    **Description**: The data in request was not encrypted or it was encrypted with obsolete keys. <br>

    **Remediation**: Encrypt the data using valid encryption keys.



    ## <span class='errorType' id="err-invalidUsername">invalidUsername</span>


    **Description**: For your security, we recommend choosing a more complex username with at least one special character. <br>

    **Remediation**: Choose a new username that satisfies the financial institution's policies or is more complex, such as including special
    characters.


    The `attributes` object in the error may have the following properties:


    | Property | Type | Description |

    |----------|------|-------------|

    | specialCharacters | string | A string containing recommended special characters. |



    ## <span class='errorType' id="err-challengedNotVerified">challengedNotVerified</span>


    **Description**: The challenge has not been verified, has expired, or has been redeemed too many times. <br>

    **Remediation**: Pass a valid and verified challenge resource in the Apiture-Challenge request header.



    ## <span class='errorType' id="err-accessDenied">accessDenied</span>


    **Description**: The credentials supplied in the request are insufficient to grant access. <br>

    **Remediation**: Check the supplied credentials for validity.



    ## <span class='errorType' id="err-currentPasswordDoesNotMatch">currentPasswordDoesNotMatch</span>


    **Description**: The current password does not match. <br>

    **Remediation**: Check that the current password in the request match the user's current password.



    ## <span class='errorType' id="err-noSuchUser">noSuchUser</span>


    **Description**: No users were found for the specified userId. <br>

    **Remediation**: Ensure the supplied userId corresponds to an Apiture user.



    ## <span class='errorType' id="err-challengeNotFound">challengeNotFound</span>


    **Description**: No Challenge was found for the specified challengeId. <br>

    **Remediation**: Ensure the supplied challengeId corresponds to a valid challenge resource.



    ## <span class='errorType' id="err-authenticatorNotFound">authenticatorNotFound</span>


    **Description**: No authenticators were found for the specified authenticatorId and challengeId combination. <br>

    **Remediation**: Ensure the supplied authenticatorId corresponds to a valid authenticator resource.



    ## <span class='errorType' id="err-noSuchDevice">noSuchDevice</span>


    **Description**: No devices were found for the specified userId. <br>

    **Remediation**: Verify that the device exists for the user and resubmit.



    ## <span class='errorType' id="err-invalidAuthenticatorState">invalidAuthenticatorState</span>


    **Description**: The operation is not allowed from the authenticator’s current state. <br>

    **Remediation**: Ensure the supplied authenticatorId corresponds to an Apiture authenticator resource in the correct state.


    The `attributes` object in the error may have the following properties:


    | Property | Type | Description |

    |----------|------|-------------|

    | currentState | string | undefined |

    | allowedStates | [undefined] | undefined |



    ## <span class='errorType' id="err-authenticatorAttemptsExceeded">authenticatorAttemptsExceeded</span>


    **Description**: User has exceeded the allowed number of retry attempts. <br>

    **Remediation**: Consider locking this user or device in order to prevent fraud.


    The `attributes` object in the error may have the following properties:


    | Property | Type | Description |

    |----------|------|-------------|

    | authenticatorId | string | undefined |

    | maximumRetries | number | undefined |

    | retryCount | number | undefined |



    ## <span class='errorType' id="err-authenticatorTypeInUse">authenticatorTypeInUse</span>


    **Description**: An update to the authenticator types omits one or more types that are in use. <br>

    **Remediation**: Include all in-use type names.


    The `attributes` object in the error may have the following properties:


    | Property | Type | Description |

    |----------|------|-------------|

    | typeNames | [undefined] | The list of authenticator types that are in use but missing from the request.<br>Example: `sms,email` |



    ## <span class='errorType' id="err-redeemChallengeConflict">redeemChallengeConflict</span>


    **Description**: No `Apiture-Challenge` request header was passed when expected, or the challenge has not been verified, has expired, or has been
    redeemed too many times. <br>

    **Remediation**: Ensure the supplied challengeId corresponds to a valid challenge resource.



    ## <span class='errorType' id="err-authenticatorNotCompletable">authenticatorNotCompletable</span>


    **Description**: The authenticator is not in a state that allows completing. <br>

    **Remediation**: Only verify an authenticator if the `apiture:verify` link exists.



    ## <span class='errorType' id="err-invalidAuthenticatorAttributes">invalidAuthenticatorAttributes</span>


    **Description**: The `attributes` in the authenticator do not conform to the schema for the authenticator type. <br>

    **Remediation**: Pass `attributes` that satisfy the JSON schema for the authenticator's type.



    ## <span class='errorType' id="err-invalidSession">invalidSession</span>


    **Description**: No session was found. <br>

    **Remediation**: Resubmit request with a valid session.



    ## <span class='errorType' id="err-challengeRefNotFound">challengeRefNotFound</span>


    **Description**: There is no challence resource corresponding to the referenced challenge. <br>

    **Remediation**: Pass a reference to a valid challence resource.



    ## <span class='errorType' id="err-authenticatorRefNotFound">authenticatorRefNotFound</span>


    **Description**: There is no authentictor resource corresponding to the referenced authentictor. <br>

    **Remediation**: Pass a reference to a valid authentictor resource.



    ## <span class='errorType' id="err-missingApitureChallengeHeader">missingApitureChallengeHeader</span>


    **Description**: The Apiture-Challenge request header is missing. <br>

    **Remediation**: Pass a reference to a valid challence resource in the Apiture-Challenge header.



    ## <span class='errorType' id="err-challengedAlreadyRedeemed">challengedAlreadyRedeemed</span>


    **Description**: The challenge resource has already been redeemed. <br>

    **Remediation**: Use the most recently issued challenge.



    ## <span class='errorType' id="err-challengedExpired">challengedExpired</span>


    **Description**: The challenge resource has expired. <br>

    **Remediation**: Use the most recently issued challenge and complete the authenticators before the challenge expires.



    ## <span class='errorType' id="err-postTokenForbidden">postTokenForbidden</span>


    **Description**: The client is not authorized to generate a new token. <br>

    **Remediation**: Use the most recently issued challenge.
  version: 0.17.1
  contact:
    name: Apiture
    url: 'https://developer.apiture.com'
    email: api@apiture.com
  termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
schemes:
  - https
basePath: /auth
tags:
  - name: OpenID Connect
    description: OpenID Connect Discovery and Authorization using OAuth 2.0
  - name: Passwords
    description: User Authentication passwords
  - name: Encryption
    description: Data Encryption
  - name: Devices
    description: User Devices
  - name: Challenges
    description: Identity Verification Challenges
  - name: Authenticators
    description: Identity Verification Authenticators
  - name: Users
    description: User Management
  - name: User Sessions
    description: User Session Life Cycles
  - name: API
    description: The Authentication API
securityDefinitions:
  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
    flow: accessCode
    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.
    authorizationUrl: /auth/oauth2/authorize
    tokenUrl: /auth/oauth2/token
    scopes:
      profiles/read: Read access to user and contact related resources.
      profiles/write: Write (update) access to user and contact related resources.
      profiles/delete: Delete access to user and auth related resources.
      profiles/readPii: >-
        Read access to personally identifiable information such as tax ID numbers, phone numbers, email and postal addresses. This must be granted in
        addition to the `profiles/read` scope in order to read such data, but is included in the `profiles/full` scope.
      profiles/full: Full access to user and contact related resources.
      admin/write: Admin write (update) access to challenges and authenticators
paths:
  /openid/metadata:
    get:
      summary: Returns OpenID Connect Discovery metadata.
      description: This request returns a JSON structure containing scopes.
      operationId: getMetadata
      security:
        - apiKey: []
      produces:
        - application/json
      tags:
        - OpenID Connect
      responses:
        '200':
          description: The metadata was returned successfully.
          schema:
            $ref: '#/definitions/authMetadata'
        '400':
          $ref: '#/responses/400'
        '422':
          $ref: '#/responses/422'
      parameters: []
  /oauth2/authorize:
    get:
      summary: Redirect to the authorization server for secure user login
      description: >-
        Start OpenID Connect Authorization Code Flow by requesting client application authorization and user authentication. This request redirects
        the user to the identity provider login page to authenticate by securely entering their credentials. Upon a successful 302 response, the
        client should validate the `Location` URI then redirect to that URI.
      operationId: authorize
      security:
        - apiKey: []
      produces:
        - application/json
      tags:
        - OpenID Connect
      parameters:
        - name: response_type
          in: query
          type: string
          enum:
            - code
            - client_credentials
          required: false
          default: code
          description: >-
            Indicates the authentication flow to be used. Use `code` to specify the usage of the OAuth 2.0 Authorization code flow and
            `client_credentials` for the OAuth 2.0 Client Credentials flow.
        - name: scope
          in: query
          type: string
          required: false
          default: openid
          description: This must be set to `openid` to indicate a request for OpenID authentication and ID token.
        - name: client_id
          in: query
          type: string
          required: true
          description: This must be set to the client ID value obtained from the client application registration process in the developer portal.
        - name: state
          in: query
          type: string
          required: false
          description: An arbitrary value set by the client to maintain state between the authorization request and the callback.
        - name: redirect_uri
          in: query
          type: string
          required: true
          description: >-
            The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value
            must match the value used during the client application registration process.  The callback url will be called with the authorization code
            provided as a parameter. Required if using the authorization_code flow.
      responses:
        '302':
          description: >-
            Complete the first phase of the Authorization Code flow. If the `Location` URI matches the `redirect_uri` parameter _and_ contains a
            `code`, the client `/authorize` request was valid and the user successfully authenticated. If the client passed a `state` parameter, the
            client should parse the `Location` URI and verify that the `state` in the `Location` matches the request. (If not, someone may be trying
            to attack the client app and steal tokens.) The client should redirect to the URI in the `Location` header. To complete the flow, that
            request handler save the `code` and pass it to [`getToken`](#op-getToken) to get an access token.
          headers:
            Location:
              type: string
              description: The redirect URI with additional parameters (`state` and `code`).
              format: uri
        '400':
          $ref: '#/responses/400'
        '401':
          description: Unauthorized. The user did not successfully authenticate.
        '422':
          $ref: '#/responses/422'
  /oauth2/token:
    post:
      summary: Obtain a secure access token.
      description: |-
        Create or refresh an access token for client use. Depending on the value of
        the `grant_type` query parameter, this operation issues a new
        access token and a refresh token at the end of the initial authentication flow,
        or it can refresh an expired or expiring access token.


        * To issue the initial token for interactive clients, use
        `?grant_type=authorization_code`,
        passing the `code` obtained from the [`authorize`](#op-authorize) operation
        and the `redirect_uri` query parameters. (Both the `code` and `redirect_uri`
        query parameters are required for this grant type.)
        Clients should save the `refresh_token` from the response.
        * For trusted (non-web, non-mobile) clients, use `?grant_type=client_credentials`
        and the `authorization` header.
        * To refresh an expiring/expired access token, use
        `?grant_type=refresh_token&refresh_token={refresh_token}`,
        using the required `{refresh_token}` that was returned in the
        _original_ [`oauthToken`](#schema-oauthToken) response from
        the earlier call to this operation.

        All calls require the `Authorization` header.
      operationId: getToken
      security:
        - apiKey: []
      produces:
        - application/json
      tags:
        - OpenID Connect
      parameters:
        - name: grant_type
          in: query
          type: string
          enum:
            - authorization_code
            - client_credentials
            - refresh_token
          required: true
          default: authorization_code
          description: >-
            This must be set to one of the following:<br> &bullet; `authorization_code` if using the OAuth 2.0 Authorization code flow<br> &bullet;
            `client_credentials` when using client-supplied credentials (key and secret)<br> &bullet; `refresh_token` when refreshing an expired or
            expiring access token.
        - name: code
          in: query
          type: string
          required: false
          description: >-
            This must be set to the authorization code returned via a callback redirect after calling the [`authorize`](#op-authorize) operation
            whenusing the OAuth 2.0 Authorization code flow. This is required if `grant_type` is `authorization_code`.
        - name: redirect_uri
          in: query
          type: string
          required: false
          description: >-
            The callback url that the user will be redirected to after successful login and consent with the Apiture Identity Provider. This value
            must match the value used during the client application registration process and the value passed to [`authorize`](#op-authorize).
            Required if using the `authorization_code` flow.
        - name: refresh_token
          in: query
          type: string
          description: The value of the `refresh_token` obtained with the original or expiring/expired access token. Required if `?grant_type=refresh_token`.
        - name: Authorization
          in: header
          type: string
          required: true
          description: >-
            Authorization credentials in the form <br> `Basic {encoded-credentials}`<br> where `{encoded-credentials}` is a Base 64 encoding of the
            text _`client-id:client-secret`_ for the registered client. If these client credentials are supplied when using the `client_credentials`
            grant, the OpenID Connect handshake is shortened and no interactive redirect is used.
      responses:
        '200':
          description: 'Return a response containing the access token, refresh token, etc.'
          schema:
            $ref: '#/definitions/oauthToken'
        '302':
          description: Indicates a redirection url has been returned to the client.
          headers:
            Location:
              type: string
              description: The login and consent page of the Apiture Identity Provider.
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '422':
          $ref: '#/responses/422'
  /usernameRequests:
    post:
      summary: Request sending the user an email containing their forgotten username.
      description: >-
        Request sending the user an email containing their forgotten username by submitting the user's key identifying information. (This operation
        does not create a resource.) An email containing the username is sent to the user as a result of this operation.
      operationId: usernameRequests
      security:
        - apiKey: []
      x-apiture-implemented: true
      produces:
        - application/json
      tags:
        - User
      parameters:
        - name: usernameRequest
          in: body
          description: The data necessary to request the user's username be sent to them.
          required: true
          schema:
            $ref: '#/definitions/usernameRequest'
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/usernameRequestNotification'
        '422':
          $ref: '#/responses/422UsernameRequest'
        '429':
          $ref: '#/responses/429'
  /passwordResetRequests:
    post:
      summary: Initiate a password reset flow.
      description: >-
        Initiate a password reset flow by sending the user's key identifying information. A confirmation code is sent to the user via text message or
        email as a result of this operation if the information matches. In order to complete the flow, a `POST` request to `/passwordReset` must
        contain the confirmation code as well as the username and the desired new password. This operation does not create a new persistent resource;
        the password reset is transient and returned in the response body only.
      operationId: passwordResetRequest
      security:
        - apiKey: []
      x-apiture-implemented: true
      produces:
        - application/json
      tags:
        - Password
      parameters:
        - name: passwordResetRequest
          in: body
          description: The data necessary to create a password reset resource.
          required: true
          schema:
            $ref: '#/definitions/passwordResetRequest'
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/passwordReset'
        '400':
          $ref: '#/responses/400'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
  /passwordResets:
    post:
      summary: Complete a password reset flow.
      description: >-
        Complete an unauthenticated password reset flow by passing `username`,`confirmationCode`, and `newPassword` in the request.  This operation
        will return 202 Accepted if the request is valid.

        This operation supports _pre-flight validation_. If invoked with the `preFlightValidate=true` query parameter, the operation validates the
        `confirmationCode` against the generated code, validates the new password to ensure it complies with the financial institution’s password
        policy, and returns an `_error` in the response if there is not a match in the codes or with details of any password policy violations.
      operationId: passwordReset
      x-apiture-unauthenticated:
        - This operation does _not_ require an access token.
      security:
        - apiKey: []
      x-apiture-implemented: true
      produces:
        - application/json
      tags:
        - Password
      parameters:
        - name: preFlightValidate
          in: query
          type: boolean
          description: 'If `true`, the operation performs pre-flight validation of the request body and it does not attempt to update the user''s password.'
        - name: passwordReset
          in: body
          description: The data necessary to confirm a password reset
          required: true
          schema:
            $ref: '#/definitions/confirmPasswordReset'
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '422':
          $ref: '#/responses/422ChangePassword'
  /my/password:
    put:
      summary: Change the user password
      description: >-
        An authenticated user must encrypt (see [`GET /encryptionKeys`]{#op-getEncryptionKeys)) and pass `currentPassword` and `newPassword` in the
        request body to change its password. This operation requires both `apiKey` and `accessToken` security.

        This operation will return 202 Accepted if the request is valid.

        If the request fails, and the user does not know the current password, they can request a password reset by using `/passwordResetRequests`.

        This operation supports _pre-flight validation_. If invoked with the `preFlightValidate=true` query parameter, the operation only validates
        the `newPassword` against the password policies and returns an `_error` in the response with details of any password policy violations.
      operationId: changeUserPassword
      security:
        - apiKey: []
          accessToken:
            - profiles/write
      x-apiture-implemented: true
      tags:
        - Password
      parameters:
        - name: preFlightValidate
          in: query
          type: boolean
          description: 'If `true`, the operation performs pre-flight validation only of the `newPassword` and it does not attempt to update the user''s password.'
        - name: password
          in: body
          required: true
          schema:
            $ref: '#/definitions/passwordChange'
      responses:
        '200':
          description: >-
            OK. The response is used for the pre-flight validation response. The `_error` object in the response, if it exists, contains error
            messages and other detail about the validation (and may contain nested errors).
          schema:
            $ref: '#/definitions/passwordChange'
        '202':
          description: Accepted
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '422':
          $ref: '#/responses/422ChangePassword'
  /encryptionKeys:
    get:
      summary: Get client-side encryption keys
      description: >-
        Get encryption keys that the client should use to encrypt sensitive data such as personally identifiable information (PII) and passwords. This
        adds security on top of transport layer security (TLS/HTTPS) so that sensitive data is not represented as plain text in request bodies.
        Clients should [encrypt properties](https://developer.apiture.com/doc/concepts/encryption) that have a <code>x-apiture-encrypt:
        {<em>keyName</em>}</code> annotation in the schema. The client adds metadata in an `_encryption` object next to the encrypted properties in
        the request body.
      operationId: getEncryptionKeys
      x-apiture-encrypt:
        names:
          - secret
      security:
        - apiKey: []
          accessToken:
            - data/read
      tags:
        - Encryption
      parameters:
        - name: keys
          in: query
          description: >-
            A list of encryption key names necessary to encrypt one or more properties in a request body. For example, if the request body schema
            contains two fields that are tagged `x-apiture-encrypt: secret`, use `?keys=secret`. If the schema contain two fields, one encrypted with
            `password` and one with the key named `pii`, use `?keys=secret,pii`
          type: array
          items:
            type: string
          collectionFormat: csv
          minLength: 1
          required: true
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/encryptionKeys'
  /confirmedUsers:
    post:
      summary: Convert a user to new digital banking platform
      description: |-
        After enabling the Apiture platform and importing customers from the banking core,
        a client application can use this operation to confirm and create a user's login account.
        The client application should prompt the user for their first and last name,
        date of birth, and tax identification number (such as a social security number)
        and submit the data here.
        A successful operation (the request was well formed) returns a
        [Challenge](#schema-challenge) resource.
        If this data matches a customer registered in the core,
        the system will connect the user resource to that customer in the banking core
        and create a new login account.


        The client should then use one of the returned challenge's
        [authenticators](schema-authenticator)
        to verify the user identity. If verified, the user enters their
        new username in the client application.
        The client should then use the [`username`](#op-createUsername) operation
        to validate and submit the user's new username to create
        the user's login account.


        This operation returns an error response if
        the data is not well formed. Since this operation is unauthenticated,
        the response for a well-formed request does _not_ indicate
        success or failure. Thus, this operation
        cannot be used to confirm if a customer exists or not.
      operationId: confirmUser
      x-apiture-unauthenticated:
        - This operation does not require an access token.
        - Users perform this before they have a login account.
      security:
        - apiKey: []
      tags:
        - User
      parameters:
        - name: userConfirmation
          in: body
          required: true
          schema:
            $ref: '#/definitions/userConfirmation'
      responses:
        '200':
          description: OK. The response does _not_ indicate if an existing user matching the data exists or not.
          schema:
            $ref: '#/definitions/userConfirmationResponse'
        '400':
          $ref: '#/responses/400'
        '429':
          $ref: '#/responses/429'
  /username:
    post:
      summary: Assign a username for a new digital banking platform user
      description: |-
        After confirming the user's identity via the [`confirmUser`](#op-confirmUser) operation
        and completing the identity verification challenge,
        the user can submit their new username with this operation.


        If there are no errors in the request, the Authentication service returns a temporary
        password to the user. The user should login with the temporary password, then change the password to one of their choosing.


        This operation also supports _pre-flight validation_, via the `?preFlightValidate=true` option,
        to request that the server validate the credentials.
        The `_error` object in the 200 `OK` response will list any such errors, such as username already in use,
        the password does not conform to the password policies, or the [Challenge ID](#schema-challenge)
        is invalid or expired or has already been redeemed.
        If the request is valid, there is no `_error` object in the pre-flight validation response.
        Validating the request does not count towards the challenge's maximum redemption count.


        This operation requires passing a valid Challenge ID in the `Apiture-Challenge`
        request header.
      operationId: createUsername
      x-apiture-unauthenticated:
        - This operation does not require an access token.
        - Users perform this before they have a login account.
      security:
        - apiKey: []
      tags:
        - User
      parameters:
        - $ref: '#/parameters/apitureChallengeHeaderParam'
        - name: preFlightValidate
          in: query
          type: boolean
          description: >-
            If `true`, the operation performs pre-flight validation of the request body and it does not attempt to create a login account and
            credentials for the user.
        - name: credentials
          in: body
          required: true
          schema:
            $ref: '#/definitions/preferredUsername'
      responses:
        '200':
          description: >-
            OK. The request was accepted and processed. If pre-flight validation was requested, the OK response indicates validation completed, but
            may have found errors in the request. If `?preFlightValidate=true`, the `_error` will list validation errors, if any.


            This error response may have one of the following `type` values:

            * [`invalidNewPassword`](#err-invalidNewPassword)

            * [`invalidUsername`](#err-invalidUsername)
          schema:
            $ref: '#/definitions/preferredUsernameResponse'
          x-apiture-errors:
            - invalidNewPassword
            - invalidUsername
        '400':
          $ref: '#/responses/400'
        '409':
          $ref: '#/responses/409PreferredUsername'
        '422':
          $ref: '#/responses/422PreferredUsername'
  /credentials:
    post:
      summary: Create credentials for a new digital banking platform user
      description: |-
        After confirming the user's identity via the [`confirmUser`](#op-confirmUser) operation
        and completing the identity verification challenge,
        the user can submit their new username and password with this operation.


        If there are no errors in the request, the user login account is completed with the requested username
        and password; the end user may now log in.


        This operation also supports _pre-flight validation_, via the `?preFlightValidate=true` option,
        to request that the server validate the credentials.
        The `_error` object in the 200 `OK` response will list any such errors, such as username already in use,
        the password does not conform to the password policies, or the [Challenge ID](#schema-challenge)
        is invalid or expired or has already been redeemed.
        If the request is valid, there is no `_error` object in the pre-flight validation response.
        Validating the request does not count towards the challenge's maximum redemption count.


        This operation requires passing a valid Challenge ID in the `Apiture-Challenge`
        request header.

        **Warning**: This operation is **deprecated** and will be removed in a future release.
      x-apiture-deprecated:
        replacement: '[`confirmUser`](#op-confirmUser) and [`createUsername`](#op-createUsername)'
        since: 0.13.2
      operationId: createCredentials
      deprecated: true
      x-apiture-unauthenticated:
        - This operation does not require an access token.
        - Users perform this before they have a login account.
      security:
        - apiKey: []
      tags:
        - User
      parameters:
        - $ref: '#/parameters/apitureChallengeHeaderParam'
        - name: preFlightValidate
          in: query
          type: boolean
          description: >-
            If `true`, the operation performs pre-flight validation of the request body and it does not attempt to create a login account and
            credentials for the user.
        - name: credentials
          in: body
          required: true
          schema:
            $ref: '#/definitions/credentials'
      responses:
        '200':
          description: >-
            OK. The request was accepted and processed. If pre-flight validation was requested, the OK response indicates validation completed, but
            may have found errors in the request. If `?preFlightValidate=true`, the `_error` will list validation errors, if any.


            This error response may have one of the following `type` values:

            * [`invalidNewPassword`](#err-invalidNewPassword)

            * [`invalidUsername`](#err-invalidUsername)
          schema:
            $ref: '#/definitions/credentialsResponse'
          x-apiture-errors:
            - invalidNewPassword
            - invalidUsername
        '400':
          $ref: '#/responses/400'
        '409':
          $ref: '#/responses/409CreateCredentials'
        '422':
          $ref: '#/responses/422CreateCredentials'
  /:
    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
      produces:
        - application/hal+json
        - application/json
      tags:
        - API
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/root'
          examples:
            application/hal+json:
              id: auth
              name: Authorization
              apiVersion: 0.1.0
              _profile: 'https://api.apiture.com/schemas/common/root/v2.0.0/profile.json'
              _links:
                'apiture:authorize':
                  href: /auth/oauth2/authorize
                'apiture:token':
                  href: /auth/oauth2/token
                'apiture:metadata':
                  href: /auth/openid/metadata
      parameters: []
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      produces:
        - application/json
        - application/openapi+json;version=2.0
        - application/openapi+yaml;version=2.0
      responses:
        '200':
          description: OK
          schema:
            type: object
      tags:
        - API
      parameters: []
  '/users/{userId}/devices':
    get:
      summary: Return a collection of devices
      description: >-
        Return a collection of devices that the user has used to sign in. This collection is small, so this operation does not support filtering,
        pagination, sorting, or searching. The Authentication API's `getRoot` operation (`GET /auth/`) will include a link `apiture:getDevices`. This
        link's `href` will resolve the `{userId}` for the currently authenticated user.
      operationId: getDevices
      x-apiture-implemented: true
      security:
        - apiKey: []
          accessToken:
            - profiles/read
      tags:
        - Devices
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/userIdPathParam'
      responses:
        '200':
          description: OK
          schema:
            type: object
            allOf:
              - $ref: '#/definitions/devices'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404Device'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
  '/users/{userId}/devices/{deviceId}':
    get:
      summary: Return a device for the user
      description: >-
        Return a specific device for a user. The `deviceId` is the unique identifier of a device resource. This operation is typically called via the
        `self` link for an item in the `getDevices` collection response.
      operationId: getDevice
      x-apiture-implemented: true
      security:
        - apiKey: []
          accessToken:
            - profiles/read
      tags:
        - Devices
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/userIdPathParam'
        - $ref: '#/parameters/deviceIdPathParam'
      responses:
        '200':
          description: OK
          schema:
            type: object
            allOf:
              - $ref: '#/definitions/device'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404Device'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
    delete:
      summary: Delete a device registration
      description: >-
        Delete a specific device registration which tracks the use of a device for a user. Once deleted, the user will have to use another secondary
        authentication method, such as entering a code sent by SMS, when signing in.
      operationId: deleteDevice
      x-apiture-implemented: true
      security:
        - apiKey: []
          accessToken:
            - profiles/delete
      tags:
        - Devices
      parameters:
        - $ref: '#/parameters/userIdPathParam'
        - $ref: '#/parameters/deviceIdPathParam'
      responses:
        '204':
          $ref: '#/responses/204Deleted'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404Device'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
  /redeemedChallenges:
    post:
      operationId: redeemChallenge
      summary: Redeem or use a challenge
      description: >-
        When an operation that requires an identity challenge (passed via the `Apiture-Challenge` request header), it _redeems_ the challenge to mark
        it as used. Challenges have a maximum number of times that they may be redeemed. This changes the `state` property of the authenticator to
        `redeemed`. This operation is available via the `apiture:redeem` link on the challenge resource, if and only if the challenge is eligible for
        the redeem operation. The response is the updated representation of the challenge.
      tags:
        - Challenge
      parameters:
        - $ref: '#/parameters/challengeQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The challenge was updated and its `state` changed to `redeemed` and the `redeemedAt` timestamp updated.
          schema:
            $ref: '#/definitions/challenge'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400RedeemChallenge'
        '409':
          $ref: '#/responses/409RedeemChallengeConflict'
        '412':
          $ref: '#/responses/412'
      security:
        - apiKey: []
          accessToken:
            - admin/write
  /retriedAuthenticators:
    post:
      operationId: retryAuthenticator
      summary: Retry an authenticator
      description: >-
        Retry or restart an authenticator, for example, if the authentication process failed or if the user never received confirmation. This changes
        the `state` property of the authenticator to `started`. This fails operation if the authenticator has been retried more than the allowed
        number of retries.


        This operation is available via the `apiture:retry` link on the authenticator resource, if and only if the authenticator is eligible for the
        retry operation. The response is the updated representation of the authenticator.
      tags:
        - Authenticator
      parameters:
        - $ref: '#/parameters/authenticatorQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The authenticator was updated and its `state` changed to `started`.
          schema:
            $ref: '#/definitions/authenticator'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400RetryAuthenticator'
        '409':
          $ref: '#/responses/409RetryAuthenticatorConflict'
        '412':
          $ref: '#/responses/412'
      security:
        - apiKey: []
  /startedAuthenticators:
    post:
      operationId: startAuthenticator
      summary: Start an authenticator
      description: >-
        Start a `pending` authenticator, initiating the identity verification. For example, starting a `sms` or `email` authenticator will send a
        unique code to the user via that channel. This changes the `state` property of the authenticator to `started` and resets the `attributes`
        data. A started authenticator should be verified via the `verifiedAuthenticator` operation. This operation is available via the
        `apiture:start` link on the authenticator resource, if and only if the authenticator is eligible for the start operation. The response is the
        updated representation of the authenticator.
      tags:
        - Authenticator
      parameters:
        - $ref: '#/parameters/authenticatorQueryParam'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The authenticator was updated and its `state` changed to `started`.
          schema:
            $ref: '#/definitions/authenticator'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400Authenticator'
        '409':
          $ref: '#/responses/409StartAuthenticatorConflict'
        '412':
          $ref: '#/responses/412'
      x-apiture-unauthenticated:
        - This operation does _not_ require an access token.
      security:
        - apiKey: []
  /verifiedAuthenticators:
    post:
      operationId: verifyAuthenticator
      summary: Verify a user's identity
      description: >-
        Complete the verification of a user's identity by `POST`ing the authenticator to this path, passing the authentication data in the
        authenticator's `attributes`. For example, to verify an `sms` or `email` authenticator, the client should send the code that was sent to the
        user via SMS or email in `attributes.code`. If the authentication data is valid, this changes the `state` property of the authenticator to
        `verified`. In addition, if all the challenges' authenticators have been verified successfully, the challenge is also marked as `verified`. If
        the `attributes` data are invalid, the authenticator is marked `failed`. Failed authenticators may be retried (restarted) via the
        `retryAuthenticator` operation.

        This operation is available via the `apiture:verify` link on the authenticator resource, if and only if the authenticator is eligible for the
        `apiture:verify` operation. The authenticator must have been started (see the `startAuthenticator` operation and the `apiture:start` link)
        before being verified. The response is the updated representation of the authenticator.
      tags:
        - Authenticator
      parameters:
        - $ref: '#/parameters/ifMatchHeaderParam'
        - name: authenticator
          in: body
          description: 'The body is the authenticator object, with the `attributes` set as per the authenticator type.'
          required: true
          schema:
            $ref: '#/definitions/authenticator'
      responses:
        '200':
          description: OK. The operation succeeded. The authenticator was updated and its `state` changed to `verified`.
          schema:
            $ref: '#/definitions/authenticator'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400Authenticator'
        '409':
          $ref: '#/responses/409VerifyAuthenticatorConflict'
        '412':
          $ref: '#/responses/412'
      x-apiture-unauthenticated:
        - This operation does _not_ require an access token.
      security:
        - apiKey: []
  '/challenges/{challengeId}/authenticators':
    parameters:
      - $ref: '#/parameters/challengeIdPathParam'
    post:
      summary: Create a new authenticator
      description: >-
        Create a new authenticator. This is only called during the creation of a new challenge resource, from the `createChallenge` operation. End
        users cannot call this operation.
      operationId: createAuthenticator
      tags:
        - Authenticator
      parameters:
        - name: authenticator
          in: body
          description: The data necessary to create a new authenticator.
          required: true
          schema:
            $ref: '#/definitions/createAuthenticator'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/authenticator'
          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`
              type: string
              format: uri
            ETag:
              description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400Authenticator'
        '404':
          $ref: '#/responses/404Challenge'
      security:
        - apiKey: []
          accessToken:
            - admin/write
  '/challenges/{challengeId}/authenticators/{authenticatorId}':
    parameters:
      - $ref: '#/parameters/challengeIdPathParam'
      - $ref: '#/parameters/authenticatorIdPathParam'
    get:
      summary: Fetch a representation of this authenticator
      description: >-
        Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this authenticator resource. This `GET` operation is
        available via the `self` link of the authenticators inside a challenge resource.
      operationId: getAuthenticator
      tags:
        - Authenticator
      parameters:
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/authenticator'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this authenticator resource.
              type: string
        '304':
          $ref: '#/responses/304'
        '404':
          $ref: '#/responses/404Authenticator'
      security:
        - apiKey: []
          accessToken:
            - profiles/read
    delete:
      summary: Delete this authenticator resource
      description: >-
        Delete this authenticator resource and any resources that are owned by it. Authenticators are deleted automatically when the challenge is
        deleted.
      operationId: deleteAuthenticator
      tags:
        - Authenticator
      responses:
        '204':
          $ref: '#/responses/204Deleted'
      security:
        - apiKey: []
          accessToken:
            - profiles/delete
      parameters: []
  /challenges:
    get:
      summary: Return a collection of challenges
      description: >-
        Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [sortable](http://developer.apiture.com/docs/concepts/sorting)
        [filterable](http://developer.apiture.com/docs/concepts/filtering) [searchable](http://developer.apiture.com/docs/concepts/searching)
        collection of challenges. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links.
      operationId: getChallenges
      tags:
        - Challenge
      parameters:
        - name: start
          in: query
          description: The zero-based index of the first challenge item to include in this page. The default 0 denotes the beginning of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: The maximum number of challenge representations to return in this page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
        - name: userId
          description: 'Subset to challenges for the specified user. The value should be the unique `{userId}` (the `_id` of a User resource).'
          in: query
          type: string
        - name: state
          in: query
          description: >-
            Subset the challenges to those whose `state` matches this value. Use `|` to separate multiple values. For example, `?state=started`
            matches only items whose `state` is `started`; `?state=verified|failed` matches items whose `state` is `verified` or `failed`. This is
            combined with an implicit `and` with other filters if they are used. See
            [filtering](https://developer.apiture.com/docs/concepts/filtering).
          type: string
          enum:
            - pending
            - started
            - verified
            - failed
            - redeemed
            - expired
      x-apiture-traits:
        filters:
          user:
            filter:
              - eq
              - ne
              - in
          state:
            filter:
              - eq
              - ne
              - in
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/challenges'
        '400':
          $ref: '#/responses/400'
        '422':
          $ref: '#/responses/422'
      security:
        - apiKey: []
          accessToken:
            - profiles/read
    post:
      summary: Create a new challenge
      description: >-
        Create a new challenge. This is called from service code when an operations requires additional user verification. By default, the resulting
        challenge resource will contain a list of authenticators, one for each authenticator type (see the `getAuthenticatorTypes` operation). When
        creating a challenge, the service can exclude authenticators with either or both `?exclude=` or specify the exact authenticator types to use
        with `?include=`.


        When an operation fails with a 401 due to required authentication response, the services embeds the challenge as the
        `_error._embedded.challenge` object in the response. See also the `getAuthenticator` operation and the `challenge` and `authenticator` schemas
        for additional details.


        A user may have only one active challenge at a time. Creating a new challenge for a user will delete any outstanding challenge resources for
        that user and any authenticators associated with those challenges. End users cannot call this operation.


        Challenges (and their authenticators) expire automatically some time after creation. At a later time, expired, failed, and verified challenges
        and authenticators are automatically deleted.
      operationId: createChallenge
      tags:
        - Challenge
      parameters:
        - name: challenge
          in: body
          description: The data necessary to create a new challenge.
          required: true
          schema:
            $ref: '#/definitions/createChallenge'
        - name: include
          in: query
          description: >-
            One or more authenticator _types_ or _categories_ which the challenge should exclude from its authenticators. Type names are from the
            `name` or `category` property of the authenticator types resource, such as `?exclude=sms`. Multiple types may be specified, separated by
            commas: `?exclude=sms,biometric`. This may be combined with the other filters, but excludes take precedent over `?include`. (This notation
            may be extended in the future to allow additional filter constraints based on authenticator type properties.)
          type: string
        - name: exclude
          in: query
          description: >-
            One or more authenticator _types_ or _categories_ which the challenge should exclude from its authenticators. Type names are from the
            `name` or `category` property of the authenticator types resource, such as `?exclude=sms`. Multiple types may be specified, separated by
            commas: `?exclude=sms,biometric`. If both `?include=`  and `?exclude=` are used, the exclusions take precedence inclusions. That is, for
            `?include=sms&exclude=sms`, the `sms` authenticator will not be used. (This notation may be extended in the future to allow additional
            filter constraints based on authenticator type properties.)
          type: string
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/challenge'
          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`
              type: string
              format: uri
            ETag:
              description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.
              type: string
        '400':
          $ref: '#/responses/400'
        '429':
          $ref: '#/responses/429'
      security:
        - apiKey: []
          accessToken:
            - admin/write
  '/challenges/{challengeId}':
    parameters:
      - $ref: '#/parameters/challengeIdPathParam'
    get:
      summary: Fetch a representation of this challenge
      description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this challenge resource.'
      operationId: getChallenge
      tags:
        - Challenge
      parameters:
        - $ref: '#/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/challenge'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this challenge resource.
              type: string
        '304':
          $ref: '#/responses/304'
        '404':
          $ref: '#/responses/404Challenge'
      security:
        - apiKey: []
          accessToken:
            - profiles/read
    delete:
      summary: Delete this challenge resource
      description: >-
        Delete this challenge resource and any authenticators that are owned by it. Challenges are also deleted at some interval after they have
        expired or at an interval after they have been redeemed.
      operationId: deleteChallenge
      tags:
        - Challenge
      responses:
        '204':
          $ref: '#/responses/204Deleted'
      security:
        - apiKey: []
          accessToken:
            - admin/delete
      parameters: []
  /authenticatorTypes:
    get:
      summary: Retrieve the set of authenticator types
      description: >-
        Return the set of reserved authenticator type names. The `type` property of a authenticator must be one of these values. This set may be
        updated by the financial institution via the `updateAuthenticatorTypes` operation. The default list includes the following types:

          * `sms`
          * `email`
      operationId: getAuthenticatorTypes
      security:
        - apiKey: []
          accessToken:
            - data/read
      tags:
        - Authenticator
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/authenticatorTypes'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update
                the resource.
              type: string
      parameters: []
    put:
      summary: Replace the set of authenticator types
      description: >-
        A financial institution can use this operation to register additional types of authenticators that they may issue to their users when a
        service needs to issue an identify verification challenge to the user. The `type` property of an authenticator must be one of these reserved
        names. This operation completely replaces the set of reserved authenticator type names, so it should include all items from the
        `getAuthenticatorTypes` that are in use. This operation is only available to financial institution administrators.
      operationId: updateAuthenticatorTypes
      security:
        - apiKey: []
          accessToken:
            - admin/write
      tags:
        - Authenticator
      parameters:
        - name: authenticatorTypes
          in: body
          description: The set of authenticator types.
          required: true
          schema:
            $ref: '#/definitions/authenticatorTypes'
        - $ref: '#/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/authenticatorTypes'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update
                the resource.
              type: string
        '400':
          description: Bad Request. The request body is badly formed or contains invalid data.
          schema:
            $ref: '#/responses/400'
        '409':
          description: Conflict. The request attempts to remove a type that is in use in existing authenticator resources.
          schema:
            $ref: '#/responses/409AuthenticatorTypesConflict'
  /userSession:
    post:
      description: |-
        Start a user's virtual session. Clients should call this to mark when a user
        logs in. This operation is not required, but using it allows the
        financial institution to monitor and audit users' sessions and help
        prevent fraudulent use. The operation returns a session identifer
        which the client should pass to continue or complete the session
        with the `continueUserSession` and `endUserSession` operations.
        The response contains links to these operations. The response
        for this operation is also passed directly to those other operations.


        This operation is idempotent. If the session has already
        been started, this operation returns that session.
      operationId: startUserSession
      security:
        - apiKey: []
          accessToken:
            - profiles/write
      tags:
        - User Sessions
      parameters:
        - name: createSession
          in: body
          description: Client information for tracking the session.
          required: true
          schema:
            $ref: '#/definitions/userSessionStart'
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/userSession'
        '400':
          description: Bad Request. The request body is badly formed or contains invalid data.
          schema:
            $ref: '#/responses/400'
        '422':
          description: >-
            Unprocessable Entity. An aspect of the request was well formed but otherwise invalid. The `_error` field in the response will contain
            details about the request error.
          schema:
            $ref: '#/responses/422UserSessionStart'
  /continuedUserSessions:
    post:
      description: |-
        Continue a session. After the client refreshes the user's access token,
        it may post the user session to this path to indicate that it wishes to continue
        the virtual session, but associated with the new token.
        The client must call this operation with the new access token in
        the `Authorization` header.


        This operation is idempotent. If the session has already
        been continued, this operation returns that session.
      operationId: continueUserSession
      security:
        - apiKey: []
          accessToken:
            - profiles/write
      tags:
        - User Sessions
      parameters:
        - name: userSession
          in: body
          description: >-
            Client information for tracking the continuing user session. This is the `userSession` returned from either the `startUserSession`
            operation or from the most recent call to `continueUserSession` for this user, whichever was most recent.
          required: true
          schema:
            $ref: '#/definitions/userSession'
      responses:
        '202':
          description: >-
            Accepted. The client should pass the response from this operation to the next call to `continueUserSession` after the current token is
            refreshed, or to the `endUserSession` operation
          schema:
            $ref: '#/definitions/userSession'
        '400':
          description: Bad Request. The request body is badly formed or contains invalid data.
          schema:
            $ref: '#/responses/400'
        '404':
          description: Not Found. The session does not exist. This error may also occur if the session has already been ended.
          schema:
            $ref: '#/responses/404'
  /completedSessions:
    post:
      description: |-
        End a user session. When the client wishes to end a user session, it can call this operation to inform the
        platform. The client may use an explicit logout operation, or it may end a session after a period of inactivity.


        Upon ending a user session, the client should purge any local cached data associated with the user and discard
        their access token and the `userSession` object.
      operationId: endUserSession
      security:
        - apiKey: []
          accessToken:
            - profiles/write
      tags:
        - User Sessions
      parameters:
        - name: userSession
          in: body
          description: >-
            Client information for tracking the current user session. This is the `userSession` returned from either the `startSession` operation or
            from the most recent call to `continueSession` for this user, whichever was most recent.
          required: true
          schema:
            $ref: '#/definitions/userSession'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request. The request body is badly formed or contains invalid data.
          schema:
            $ref: '#/responses/400'
        '404':
          description: Not Found. The user session does not exist. This error may also occur if the user session has already been ended.
          schema:
            $ref: '#/responses/404'
parameters:
  apitureChallengeHeaderParam:
    name: Apiture-Challenge
    description: >-
      The unique identifier of a Challenge resource which demonstrates the user has recently verified their identity. See the discussion of
      _Multi-factor authentication challenges_ above. The value must be the `_id` string of a valid, redeemable Challenge resource which matches the
      challenge context.
    in: header
    type: string
    required: false
  userIdPathParam:
    name: userId
    in: path
    description: The user ID of a user. An authenticated user can only view their own devices.
    type: string
    required: true
  deviceIdPathParam:
    name: deviceId
    description: The unique identifier of the device.
    in: path
    type: string
    required: true
  challengeQueryParam:
    name: challenge
    required: true
    in: query
    type: string
    description: A string which uniquely identifies an challenge. This may be the unique `_id` of the challenge resource or the URI of the challenge.
  authenticatorQueryParam:
    name: authenticator
    required: true
    in: query
    type: string
    description: A string which uniquely identifies an authenticator. This may be the unique `_id` of the authenticator or the URI of the authenticator.
  authenticatorIdPathParam:
    name: authenticatorId
    description: The unique identifier of this authenticator. This is an opaque string.
    in: path
    type: string
    required: true
  challengeIdPathParam:
    name: challengeId
    description: The unique identifier of this challenge. This is an opaque string.
    in: path
    type: string
    required: true
  ifMatchHeaderParam:
    name: If-Match
    description: >-
      The entity tag that was returned in the `ETag` response. The `If-Match` header is optional, but if passed, this must match the current entity
      tag of the resource.
    in: header
    type: string
    required: false
  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` will return 304 (Not Modified)
      and no response body, else the resource representation will be returned.
    in: header
    type: string
    required: false
  filterQueryParam:
    name: filter
    in: query
    description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
    type: string
  qQueryParam:
    name: q
    in: query
    description: 'Optional search string. See [searching](http://developer.apiture.com/docs/concepts/searching).'
    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 will contain details about the
      request error.
    schema:
      $ref: '#/definitions/errorResponse'
  '401':
    description: |-
      The client did not include credentials or the credentials are not valid, or the `access_token` has expired and should be refreshed.

      This error response may have one of the following `type` values:
      * [`accessDenied`](#err-accessDenied)
      * [`getTokenAccessDenied`](#err-getTokenAccessDenied)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - accessDenied
      - getTokenAccessDenied
  '403':
    description: |-
      Forbidden. The user or client is not allowed to perform this operation

      This error response may have one of the following `type` values:
      * [`postTokenForbidden`](#err-postTokenForbidden)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - postTokenForbidden
  '404':
    description: |-
      Not Found. The session does not exist.

      This error response may have one of the following `type` values:
      * [`invalidSession`](#err-invalidSession)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - invalidSession
  '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.
    schema:
      $ref: '#/definitions/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.
    schema:
      $ref: '#/definitions/errorResponse'
  '429':
    description: >-
      Too Many Requests.  If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until a
      period of time has passed.
    schema:
      $ref: '#/definitions/errorResponse'
  '500':
    description: Server Error. Fatal error has occurred.
    schema:
      $ref: '#/definitions/errorResponse'
  422UsernameRequest:
    description: |-
      Username request is invalid.

      This error response may have one of the following `type` values:
      * [`invalidUsernameRequest`](#err-invalidUsernameRequest)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - invalidUsernameRequest
  422UserSessionStart:
    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.
    schema:
      $ref: '#/definitions/errorResponse'
  422CreateCredentials:
    description: |-
      Unprocessable Entity. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.

      This error response may have one of the following `type` values:
      * [`challengeRefNotFound`](#err-challengeRefNotFound)
      * [`invalidNewPassword`](#err-invalidNewPassword)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - challengeRefNotFound
      - invalidNewPassword
  204Deleted:
    description: No Content. The resource was deleted successfully.
  404Device:
    description: |-
      The device was not found. The `_error` field in the response will contain details about the request error.

      This error response may have one of the following `type` values:
      * [`noSuchUser`](#err-noSuchUser)
      * [`noSuchDevice`](#err-noSuchDevice)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - noSuchUser
      - noSuchDevice
  422ChangePassword:
    description: |-
      Current password does not match or invalid new password.

      This error response may have one of the following `type` values:
      * [`currentPasswordDoesNotMatch`](#err-currentPasswordDoesNotMatch)
      * [`invalidNewPassword`](#err-invalidNewPassword)
      * [`dataNotEncrypted`](#err-dataNotEncrypted)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - currentPasswordDoesNotMatch
      - invalidNewPassword
      - dataNotEncrypted
  400RedeemChallenge:
    description: |-
      Bad Request. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.

      This error response may have one of the following `type` values:
      * [`challengeRefNotFound`](#err-challengeRefNotFound)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - challengeRefNotFound
  422PreferredUsername:
    description: |-
      Unprocessable Entity. The challenge parameter was malformed or does not refer to an existing or accessible challenge resource.

      This error response may have one of the following `type` values:
      * [`challengeRefNotFound`](#err-challengeRefNotFound)
      * [`invalidNewPassword`](#err-invalidNewPassword)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - challengeRefNotFound
      - invalidNewPassword
  409PreferredUsername:
    description: >-
      Conflict. The username is already in use, or no `Apiture-Challenge` request header was passed when expected, or the challenge has not been
      verified, has expired, or has been redeemed too many times, or the account has already been confirmed.


      This error response may have one of the following `type` values:

      * [`missingApitureChallengeHeader`](#err-missingApitureChallengeHeader)

      * [`challengedNotVerified`](#err-challengedNotVerified)

      * [`challengedExpired`](#err-challengedExpired)

      * [`challengedAlreadyRedeemed`](#err-challengedAlreadyRedeemed)

      * [`invalidUsername`](#err-invalidUsername)

      * [`accountAlreadyConfirmed`](#err-accountAlreadyConfirmed)
    schema:
      $ref: '#/definitions/challengeErrorResponse'
    x-apiture-errors:
      - missingApitureChallengeHeader
      - challengedNotVerified
      - challengedExpired
      - challengedAlreadyRedeemed
      - invalidUsername
      - accountAlreadyConfirmed
  409CreateCredentials:
    description: >-
      Conflict. The username is already in use, or no `Apiture-Challenge` request header was passed when expected, or the challenge has not been
      verified, has expired, or has been redeemed too many times, or the account has already been confirmed.


      This error response may have one of the following `type` values:

      * [`missingApitureChallengeHeader`](#err-missingApitureChallengeHeader)

      * [`challengedNotVerified`](#err-challengedNotVerified)

      * [`challengedExpired`](#err-challengedExpired)

      * [`challengedAlreadyRedeemed`](#err-challengedAlreadyRedeemed)

      * [`invalidUsername`](#err-invalidUsername)

      * [`accountAlreadyConfirmed`](#err-accountAlreadyConfirmed)
    schema:
      $ref: '#/definitions/challengeErrorResponse'
    x-apiture-errors:
      - missingApitureChallengeHeader
      - challengedNotVerified
      - challengedExpired
      - challengedAlreadyRedeemed
      - invalidUsername
      - accountAlreadyConfirmed
  409RedeemChallengeConflict:
    description: |-
      Conflict. The request to redeem the challenged is not allowed. The `_error` field in the response will contain details about the request error.

      This error response may have one of the following `type` values:
      * [`redeemChallengeConflict`](#err-redeemChallengeConflict)
    x-apiture-errors:
      - redeemChallengeConflict
  400RetryAuthenticator:
    description: |-
      Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator.

      This error response may have one of the following `type` values:
      * [`authenticatorRefNotFound`](#err-authenticatorRefNotFound)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorRefNotFound
  409RetryAuthenticatorConflict:
    description: >-
      Conflict. The request to retry the authenticator is not allowed. The `_error` field in the response will contain details about the request
      error.


      This error response may have one of the following `type` values:

      * [`authenticatorAttemptsExceeded`](#err-authenticatorAttemptsExceeded)

      * [`invalidAuthenticatorState`](#err-invalidAuthenticatorState)
    x-apiture-errors:
      - authenticatorAttemptsExceeded
      - invalidAuthenticatorState
  400Authenticator:
    description: >-
      Bad Request. The authenticator parameter was malformed or does not refer to an existing or accessible authenticator, or the request body was not
      well formed.


      This error response may have one of the following `type` values:

      * [`authenticatorRefNotFound`](#err-authenticatorRefNotFound)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorRefNotFound
  409StartAuthenticatorConflict:
    description: >-
      Conflict. The request to start the authenticator is not allowed. The `_error` field in the response will contain details about the request
      error.


      This error response may have one of the following `type` values:

      * [`authenticatorAttemptsExceeded`](#err-authenticatorAttemptsExceeded)

      * [`invalidAuthenticatorState`](#err-invalidAuthenticatorState)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorAttemptsExceeded
      - invalidAuthenticatorState
  409VerifyAuthenticatorConflict:
    description: >-
      Conflict. The request to verify the authenticator is not allowed. The `_error` field in the response will contain details about the request
      error.


      This error response may have one of the following `type` values:

      * [`authenticatorNotCompletable`](#err-authenticatorNotCompletable)

      * [`invalidAuthenticatorAttributes`](#err-invalidAuthenticatorAttributes)

      * [`invalidAuthenticatorState`](#err-invalidAuthenticatorState)

      * [`authenticatorAttemptsExceeded`](#err-authenticatorAttemptsExceeded)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorNotCompletable
      - invalidAuthenticatorAttributes
      - invalidAuthenticatorState
      - authenticatorAttemptsExceeded
  404Authenticator:
    description: >-
      Not Found. There is no such authenticator resource at the specified `{authenticatorId}`. The `_error` field in the response will contain details
      about the request error.


      This error response may have one of the following `type` values:

      * [`authenticatorNotFound`](#err-authenticatorNotFound)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorNotFound
  404Challenge:
    description: >-
      Not Found. There is no such challenge resource at the specified `{challengeId}`. The `_error` field in the response will contain details about
      the request error.


      This error response may have one of the following `type` values:

      * [`challengeNotFound`](#err-challengeNotFound)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - challengeNotFound
  409AuthenticatorTypesConflict:
    description: >-
      Conflict: The request body conflicts with existing state. The request must include (not remove) all types in use by existing
      authenticators/challenges.


      This error response may have one of the following `type` values:

      * [`authenticatorTypeInUse`](#err-authenticatorTypeInUse)
    schema:
      $ref: '#/definitions/errorResponse'
    x-apiture-errors:
      - authenticatorTypeInUse
definitions:
  usernameRequest:
    title: Username request (v1.0.0)
    description: A request to send a forgotten login username to a user. The user must provide some personal data which helps locate the user.
    required:
      - lastName
      - taxId
      - birthdate
    example:
      lastName: Smith
      taxId: '1234'
      birthdate: '1975-02-28'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - lastName
          - taxId
          - birthdate
    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.'
        $ref: '#/definitions/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
      lastName:
        description: The user's last name(case sensitive).
        type: string
        example: Smith
      taxId:
        description: Last 4 digits of the user tax ID.
        type: string
        minLength: 4
        maxLength: 4
        example: '1234'
      birthdate:
        description: 'The user''s birth date in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` date format.'
        type: string
        format: date
        example: '1975-02-28'
    type: object
    x-apiture-flattened: true
  passwordResetRequest:
    title: Password Reset Request (v1.0.0)
    description: Create a new password reset.
    required:
      - username
      - taxId
      - birthdate
    example:
      username: john0224
      taxId: '1234'
      birthdate: '1974-10-27'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - properties:
          - username
          - taxId
          - birthdate
    properties:
      username:
        description: The user's username.
        type: string
        example: john0224
      taxId:
        description: Last 4 digits of the user tax ID.
        type: string
        minLength: 4
        maxLength: 4
        example: '1234'
      birthdate:
        description: 'The user''s birth date in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` date format.'
        type: string
        format: date
        example: '1974-10-27'
    type: object
    x-apiture-flattened: true
  passwordReset:
    title: Password Reset (v1.0.0)
    description: Password reset resource.
    example:
      codeDeliveryMethod: email
      codeDestination: b***@m***.com
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - properties:
          - codeDeliveryMethod
          - codeDestination
    properties:
      codeDeliveryMethod:
        description: Confirmation code delivery method.
        type: string
        enum:
          - sms
          - email
      codeDestination:
        description: Masked email address or phone number the confirmation code is sent to.
        type: string
    type: object
    x-apiture-flattened: true
  usernameRequestNotification:
    title: Username Request (v1.0.0)
    description: Username request resource.
    example:
      lastName: Smith
      taxId: '1234'
      birthdate: '1975-02-28'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - properties:
          - lastName
          - taxId
          - birthdate
    properties:
      lastName:
        description: Last name of user
        type: string
      taxId:
        description: Last 4 digits of the user tax ID.
        type: string
      birthdate:
        description: 'The user''s birth date in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` date format.'
        type: string
    type: object
    x-apiture-flattened: true
  authMetadata:
    title: Authentication metadata (v1.0.0)
    description: >-
      A map of (name, value) pairs which describe then the [OpenID Provider
      metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
    type: object
    x-apiture-version: 1.0.0
    properties: {}
    x-apiture-flattened: true
  oauthToken:
    title: OAuth Tokens (v1.0.0)
    description: A response from a credentialed request for tokens.
    type: object
    properties:
      access_token:
        type: string
        description: >-
          An opaque string which should be passed (along with the `token_type`) to subsequent API calls which require authentication.  Normally this
          is done via the the `Authorization` header of the request: from this response: <p> `Authorization:` _`token_type` `access_token`_
      token_type:
        type: string
        description: >-
          The form of token returned. This is typically the string `Bearer` and is the key which subsequent calls should use (along with the
          `access_token` above) in the `Authorization` header when making authenticated API requests.
      expires_in:
        type: integer
        format: int64
        description: 'The number of seconds until the `access_token` expires. When it expires, use the `refresh_token` to request a new access token.'
      refresh_token:
        type: string
        description: >-
          A token to use when the `access_token` expires. The client should retain this securely so it can obtain a new `access_token` later when the
          access token expires.
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  attributes:
    x-apiture-version: 2.0.0
    title: Attributes
    description: An optional map of name/value pairs which contains additional dynamic data about the resource.
    type: object
    x-apiture-key: attributeName
    additionalProperties:
      $ref: '#/definitions/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
  passwordChange:
    title: Password change (v1.0.0)
    description: >-
      Representation used to change a user password. The request must contain the `currentPassword`, the `newPassword`. The client encrypts these
      values using the [`secret` encryption key](#op-getEncryptionKeys) and store the corresponding encryption key aliases in the [`_encryption`
      metadata](https://developer.apiture.com/doc/concepts/encryption) property.
    x-apiture-encrypt:
      names:
        - secret
    example:
      currentPassword: dhjke45785huryur89rid7liuld8973hdodhwliw474hq4gp47h
      newPassword: 5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4
      _encryption:
        currentPassword: secret-48729783
        newPassword: secret-48729783
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - properties:
          - currentPassword
          - newPassword
          - _encryption
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      currentPassword:
        description: >-
          The user's current encrypted user password. The client should prompt the user for their current password, then encrypt it with the `secret`
          encryption key.
        type: string
        format: encrypted-password
        x-apiture-encrypt: secret
      newPassword:
        description: |-
          The user's encrypted new password.
           The client should prompt the user for their new password,
           then encrypt it with the `secret` encryption key.
        type: string
        format: encrypted-password
        x-apiture-encrypt: secret
      _encryption:
        description: Metadata about the encrypted `currentPassword` and `newPassword` properties.
        allOf:
          - $ref: '#/definitions/encryptionMetadata'
        example:
          currentPassword: secret-48729783
          newPassword: secret-48729783
    type: object
    x-apiture-flattened: true
  confirmPasswordReset:
    title: Confirm Password Reset (v1.0.0)
    description: Representation used to confirm a password reset flow.
    x-apiture-encrypt:
      names:
        - secret
    example:
      _profile: 'https://api.apiture.com/schemas/auth/confirmPasswordReset/v1.0.0/profie.json'
      username: john0224
      newPassword: 5ufouoi45iofliskutyw4u6k34hkfjoe98yw4iylliweo72phh4
      confirmationCode: '12345'
      _encryption:
        newPassword: secret-48729783
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - newPassword
          - confirmationCode
          - username
          - _encryption
    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.'
        $ref: '#/definitions/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
      newPassword:
        description: >-
          The user's encrypted new password. The client should prompt the user for their new password, then encrypt it with the `secret` encryption
          key.
        type: string
        format: encrypted-password
        x-apiture-encrypt: secret
      confirmationCode:
        description: A confirmation code send when the user initiated password reset.
        type: string
        example: '541683'
      username:
        description: The username.
        type: string
      _encryption:
        description: Metadata about the encrypted `newPassword` property.
        allOf:
          - $ref: '#/definitions/encryptionMetadata'
        example:
          newPassword: secret-48729783
    type: object
    x-apiture-flattened: true
  preferredUsername:
    title: Preferred Username (v1.0.1)
    description: A new user's requested username.
    x-apiture-version: 1.0.1
    example:
      _profile: 'https://api.apiture.com/schemas/auth/credentials/v1.0.1/profie.json'
      username: john0224
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - username
    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.'
        $ref: '#/definitions/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 user's requested username.
        type: string
    type: object
    x-apiture-flattened: true
  preferredUsernameResponse:
    title: Preferred Username Response (v1.0.0)
    description: Response from submitting new username for a new user login account.
    example:
      _profile: 'https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json'
      temporaryPassword: '#pbw+`XNtwPf5,K7'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - properties:
          - temporaryPassword
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      temporaryPassword:
        description: The temporary password created by the service.
        type: string
    type: object
    x-apiture-flattened: true
  credentials:
    title: New user credentials (v1.0.0)
    description: >-
      A new user's requested username and password.<br>**Warning**: The schema `credentials` was deprecated on version `v0.13.2` of the API. Use
      [`confirmUser`](#op-confirmUser) and [`createUserName`](#op-createUsername) instead. `credentials` will be removed on version `v1.0.0` of the
      API.
    x-apiture-deprecated:
      replacement: '[`confirmUser`](#op-confirmUser) and [`createUserName`](#op-createUsername)'
      since: 0.13.2
    example:
      _profile: 'https://api.apiture.com/schemas/auth/credentials/v1.0.0/profie.json'
      username: john0224
      password: newPassword
      confirmationCode: '12345'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - password
          - username
    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.'
        $ref: '#/definitions/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
      password:
        description: A new user's password.
        type: string
        format: encrypted-password
      username:
        description: The user's requested username.
        type: string
    type: object
    x-apiture-flattened: true
  credentialsResponse:
    title: Credentials Response (v1.0.0)
    description: Response from submitting new username and password for a new user login account.
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/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.'
        $ref: '#/definitions/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: '#/definitions/error'
    type: object
    x-apiture-flattened: true
  commonDeviceFields:
    title: Common Device Fields (v1.0.0)
    description: Device properties shared by other schemas.
    x-apiture-fragment: true
    type: object
    properties:
      _id:
        description: The device unique identifier.
        readOnly: true
        type: string
      operatingSystem:
        type: string
        description: >-
          The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the
          value could not be determined.
        readOnly: true
        maxLength: 16
      vendor:
        type: string
        description: >-
          The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be
          determined.
        readOnly: true
        maxLength: 16
      secondaryId:
        description: 'An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.'
        type: string
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  device:
    title: Device (v1.0.0)
    description: A device which the user has used to sign in to digital banking.
    example:
      _profile: 'https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json'
      _id: us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1
      name: 'Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0'
      lastIpAddress: 34.198.94.30
      trusted: false
      lastLoggedInAt: '2019-06-25T11:48:18.000Z'
      userId: testUser
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/commonDeviceFields'
      - properties:
          - name
          - type
          - lastIpAddress
          - trusted
          - lastLoggedInAt
          - userId
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      _id:
        description: The device unique identifier.
        readOnly: true
        type: string
      operatingSystem:
        type: string
        description: >-
          The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the
          value could not be determined.
        readOnly: true
        maxLength: 16
      vendor:
        type: string
        description: >-
          The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be
          determined.
        readOnly: true
        maxLength: 16
      secondaryId:
        description: 'An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.'
        type: string
      name:
        type: string
        description: 'The name of the device, derived from the authentication flow.'
        readOnly: true
      type:
        type: string
        description: >-
          The type (category) of the device, if known. 'mobile', 'desktop' are examples. An empty or omitted value indicates the value could not be
          determined.
        readOnly: true
        maxLength: 16
      lastIpAddress:
        type: string
        description: The IP address used when the user last logged in with this device.
      trusted:
        type: boolean
        description: >-
          If `true`, the user indicated that the device is trusted when signing in on the device. Future sign ins on the device will not require
          alternate multi-factor authentication such as entering a code sent by the financial institution via SMS. If `false`, the user has not
          indicated the specific device is trusted.
      lastLoggedInAt:
        type: string
        description: 'The timestamp of last login. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339)  format, `YYYY-MM-DDThh:mm:ss.sssZ`'
        format: date-time
      userId:
        type: string
        description: The user identified by `userId`.
    type: object
    x-apiture-flattened: true
  devices:
    title: Devices (v1.0.0)
    description: A collection of devices which user uses to sign in.
    example:
      _profile: 'https://api.apiture.com/schemas/auth/devices/v1.0.0/profile.json'
      start: 0
      limit: 100
      count: 1
      name: devices
      _links:
        collection:
          href: /auth/users/testUser/devices
      _embedded:
        items:
          - _profile: 'https://api.apiture.com/schemas/auth/device/v1.0.0/profile.json'
            _id: us-east-1_b6530c4c-572a-403a-9452-cd0c74c715a1
            name: 'Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0'
            lastIpAddress: 34.198.94.30
            trusted: false
            lastLoggedInAt: '2019-06-25T11:48:18.000Z'
            userId: testUser
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/collection'
      - 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.'
        $ref: '#/definitions/links'
      _embedded:
        type: object
        description: Embedded device objects.
        properties:
          items:
            description: An array of devices which user uses to sign in.
            type: array
            items:
              $ref: '#/definitions/device'
      _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: '#/definitions/error'
      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
    type: object
    x-apiture-flattened: true
  authenticatorFields:
    title: Authenticator Fields (v1.0.0)
    description: Common fields of an authenticator.
    x-apiture-fragment: true
    properties:
      type:
        description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
        allOf:
          - $ref: '#/definitions/authenticatorType'
      maximumRetries:
        description: >-
          The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an
          authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user
          cannot retry the authenticator. The default is `3`.
        type: integer
        minimum: 0
        maximum: 10
    x-apiture-version: 1.0.0
    type: object
    x-apiture-flattened: true
  createAuthenticator:
    title: Create Authenticator (v1.0.0)
    description: A request to create a new authenticator.
    required:
      - type
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/authenticatorFields'
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      type:
        description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
        allOf:
          - $ref: '#/definitions/authenticatorType'
      maximumRetries:
        description: >-
          The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an
          authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user
          cannot retry the authenticator. The default is `3`.
        type: integer
        minimum: 0
        maximum: 10
    type: object
    x-apiture-flattened: true
  authenticator:
    title: Authenticator (v1.0.0)
    description: >
      Representation of authenticators which verify a user's identity.



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


      Response and request bodies using this <strong><code>authenticator</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-retryAuthenticator'><strong><code>apiture:retry</code></strong></a></td><td>Retry an
      authenticator</td><td><code>POST</code></td>

      </tr>


      <tr>

      <td><a href='#op-startAuthenticator'><strong><code>apiture:start</code></strong></a></td><td>Start an
      authenticator</td><td><code>POST</code></td>

      </tr>


      <tr>

      <td><a href='#op-verifyAuthenticator'><strong><code>apiture:verify</code></strong></a></td><td>Verify a user's
      identity</td><td><code>POST</code></td>

      </tr>


      <tr>

      <td><a href='#op-getChallenge'><strong><code>apiture:challenge</code></strong></a></td><td>Fetch a representation of this
      challenge</td><td><code>GET</code></td>

      </tr>

      </table>
    example:
      _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
      _profile: 'https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json'
      userId: b2720469-3497-4b82-8b85-30f2155aa66d
      state: started
      type:
        name: sms
        label: SMS Code
        description: Enter a code sent via SMS to the user's preferred mobile device.
        category: device
        schema:
          title: SMS attributes
          description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
          type: object
          required:
            - code
            - length
          properties:
            code:
              type: string
              description: >-
                A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to
                that. The length of the code (the number of characters or digits) must equal the `length'.
              minLength: 3
              maxLength: 10
            length:
              description: The number of digits/characters that are sent to the user via SMS.
              type: integer
              minimum: 3
              maximum: 10
              example: 6
      maximumRetries: 3
      retryCount: 1
      createdAt: '2019-08-23T12:42:50.375Z'
      expiresAt: '2019-08-23T13:12:50.375Z'
      _links:
        self:
          href: /auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
        'apiture:challenge':
          href: /auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e
        'apiture:retry':
          href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
        'apiture:verify':
          href: /auth/challenges/verifiedAuthenticators
    x-apiture-links:
      - rel: 'apiture:retry'
        operationId: retryAuthenticator
      - rel: 'apiture:start'
        operationId: startAuthenticator
      - rel: 'apiture:verify'
        operationId: verifyAuthenticator
      - rel: 'apiture:challenge'
        operationId: getChallenge
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/authenticatorFields'
      - properties:
          - _id
          - userId
          - state
          - retryCount
          - attributes
          - createdAt
          - verifiedAt
          - failedAt
          - 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.'
        $ref: '#/definitions/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: '#/definitions/error'
      type:
        description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
        allOf:
          - $ref: '#/definitions/authenticatorType'
      maximumRetries:
        description: >-
          The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an
          authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user
          cannot retry the authenticator. The default is `3`.
        type: integer
        minimum: 0
        maximum: 10
      _id:
        description: The unique identifier for this authenticator resource. This is an immutable opaque string assigned upon creation.
        readOnly: true
        type: string
      userId:
        description: The user ID of the user who is requested to verify their identity.
        type: string
      state:
        description: The state of this authenticator. This is derived and read-only.
        allOf:
          - $ref: '#/definitions/authenticatorState'
        readOnly: true
      retryCount:
        description: The actual number of times a user has retried this authenticator.
        type: integer
        minimum: 0
        maximum: 10
        readOnly: true
      attributes:
        description: >-
          Data collected from the user that is used to verify this authenticator. This data conforms to the schema defined in the `type`. For example,
          for `sms`, the `attributes` must contains a `code`.
        type: object
      createdAt:
        description: >-
          The time stamp when authenticator was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      verifiedAt:
        description: >-
          The time stamp when authenticator was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      failedAt:
        description: >-
          The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC
          3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      expiresAt:
        description: >-
          The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
    type: object
    x-apiture-flattened: true
  challengeFields:
    title: Challenge Fields (v1.0.0)
    description: Properties of challenge objects.
    x-apiture-fragment: true
    properties:
      reason:
        description: >-
          The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
          informational purposes.
        type: string
        x-apiture-todo:
          - Should this be a reasonCode (non-localizable identifier and reason label?
      contextUri:
        description: >-
          The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
          for a pending transfer, a user's mailing address, or an account if adding a joint owner.
        type: string
        format: uri
        maxLength: 2048
      userId:
        description: >-
          The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
          challenge.
        type: string
      minimumAuthenticatorCount:
        description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
        type: integer
        minimum: 0
        maximum: 4
      maximumRedemptionCount:
        description: The maximum number of times the challenge may be used or redeemed. The default is 1.
        type: integer
        minimum: 1
    x-apiture-version: 1.0.0
    type: object
    x-apiture-flattened: true
  createChallenge:
    title: Create Challenge (v1.0.0)
    description: A request to create a user authentication challenge.
    required:
      - reason
      - contextUri
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/challengeFields'
      - properties:
          - code
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      reason:
        description: >-
          The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
          informational purposes.
        type: string
        x-apiture-todo:
          - Should this be a reasonCode (non-localizable identifier and reason label?
      contextUri:
        description: >-
          The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
          for a pending transfer, a user's mailing address, or an account if adding a joint owner.
        type: string
        format: uri
        maxLength: 2048
      userId:
        description: >-
          The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
          challenge.
        type: string
      minimumAuthenticatorCount:
        description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
        type: integer
        minimum: 0
        maximum: 4
      maximumRedemptionCount:
        description: The maximum number of times the challenge may be used or redeemed. The default is 1.
        type: integer
        minimum: 1
      code:
        description: >-
          An optional opaque code string which a service may assign when using the Challenge API to satisfy the deployment's authentication challenge.
          This code is returned in the [challenge resource](#op-getChallenge) only when the user has successfully verified the challenge. The client
          may use this code to complete the authentication provider's authentication flow.
        type: string
        minLength: 16
        maxLength: 128
    type: object
    x-apiture-flattened: true
  summaryChallenge:
    title: Summary Challenge (v1.0.0)
    description: 'Summary representation of a challenge, used in the challenge collection.'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/challengeFields'
      - properties:
          - _id
          - redemptionCount
          - state
          - createdAt
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      reason:
        description: >-
          The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
          informational purposes.
        type: string
        x-apiture-todo:
          - Should this be a reasonCode (non-localizable identifier and reason label?
      contextUri:
        description: >-
          The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
          for a pending transfer, a user's mailing address, or an account if adding a joint owner.
        type: string
        format: uri
        maxLength: 2048
      userId:
        description: >-
          The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
          challenge.
        type: string
      minimumAuthenticatorCount:
        description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
        type: integer
        minimum: 0
        maximum: 4
      maximumRedemptionCount:
        description: The maximum number of times the challenge may be used or redeemed. The default is 1.
        type: integer
        minimum: 1
      _id:
        description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
        readOnly: true
        type: string
      redemptionCount:
        description: How many times the challenge has been redeemed.
        type: integer
        readOnly: true
      state:
        description: The state of this authenticator.
        allOf:
          - $ref: '#/definitions/challengeState'
        readOnly: true
      createdAt:
        description: >-
          The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
    type: object
    x-apiture-flattened: true
  challenge:
    title: Challenge (v1.0.0)
    description: >
      A resource which represents an identity verification challenge to a user. The user must verify one or more of the authentication methods defined
      in this challenge in order to proceed with a banking operation (such as scheduling a larger than normal transfer, adding a joint owner or
      authorized signer to an account, or changing their mailing address or mobile phone number).



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


      Response and request bodies using this <strong><code>challenge</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-redeemChallenge'><strong><code>apiture:redeem</code></strong></a></td><td>Redeem or use a
      challenge</td><td><code>POST</code></td>

      </tr>

      </table>
    example:
      _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
      _profile: 'https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json'
      reason: Transfer amount much higher than normal
      contextUri: 'https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1'
      minimumAuthenticatorCount: 1
      authenticators:
        - _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
          _profile: 'https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/profile.json'
          userId: b2720469-3497-4b82-8b85-30f2155aa66d
          state: started
          type:
            name: sms
            label: SMS Code
            description: Enter a code sent via SMS to the user's preferred mobile device.
            category: device
            schema:
              title: SMS attributes
              description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
              type: object
              required:
                - code
                - length
              properties:
                code:
                  type: string
                  description: >-
                    A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to
                    that. The length of the code (the number of characters or digits) must equal the `length'.
                  minLength: 3
                  maxLength: 10
                length:
                  description: The number of digits/characters that are sent to the user via SMS.
                  type: integer
                  minimum: 3
                  maximum: 10
                  example: 6
          maximumRetries: 3
          retryCount: 1
          createdAt: '2019-08-23T12:42:50.375Z'
          expiresAt: '2019-08-23T13:12:50.375Z'
          _links:
            self:
              href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
            'apiture:challenge':
              href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c
            'apiture:retry':
              href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
            'apiture:verify':
              href: /auth/challenges/verifiedAuthenticators
      maximumRedemptionCount: 1
      redemptionCount: 0
      state: pending
      createdAt: '2019-08-23T11:37:55.375Z'
      expiresAt: '2019-08-23T12:37:55.375Z'
      _links:
        self:
          href: /auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a
        'apiture:redeem':
          href: /auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a
    x-apiture-links:
      - rel: 'apiture:redeem'
        operationId: redeemChallenge
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - $ref: '#/definitions/summaryChallenge'
      - properties:
          - _id
          - authenticators
          - redeemable
          - verifiedAt
          - failedAt
          - expiresAt
          - redemptionHistory
          - code
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      reason:
        description: >-
          The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
          informational purposes.
        type: string
        x-apiture-todo:
          - Should this be a reasonCode (non-localizable identifier and reason label?
      contextUri:
        description: >-
          The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
          for a pending transfer, a user's mailing address, or an account if adding a joint owner.
        type: string
        format: uri
        maxLength: 2048
      userId:
        description: >-
          The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
          challenge.
        type: string
      minimumAuthenticatorCount:
        description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
        type: integer
        minimum: 0
        maximum: 4
      maximumRedemptionCount:
        description: The maximum number of times the challenge may be used or redeemed. The default is 1.
        type: integer
        minimum: 1
      _id:
        description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
        readOnly: true
        type: string
      redemptionCount:
        description: How many times the challenge has been redeemed.
        type: integer
        readOnly: true
      state:
        description: The state of this authenticator.
        allOf:
          - $ref: '#/definitions/challengeState'
        readOnly: true
      createdAt:
        description: >-
          The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      authenticators:
        description: >-
          An array of authenticators with which the user can verify their identity. This is derived; the array and the authenticators are constructed
          in the `createChallenge` operation.
        type: array
        items:
          $ref: '#/definitions/authenticator'
        readOnly: true
      redeemable:
        description: >-
          `true` if and only if the challenge may be redeemed. This is derived from the states of the challenge's authenticators; if the number of
          `verified` authenticators meets or exceeds the `minimumAuthenticatorCount`, the challenge becomes `verified` and may be redeemed via a
          `POST` to href in the challenge's `apiture:redeem` link.
        type: boolean
        readOnly: true
      verifiedAt:
        description: >-
          The time stamp when challenge was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      failedAt:
        description: >-
          The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC
          3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      expiresAt:
        description: >-
          The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`).
        type: string
        format: date-time
        readOnly: true
      redemptionHistory:
        description: >-
          The time stamps when a service or operation redeemed this challenge, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
          (`YYYY-MM-DDThh:mm:ss.sssZ`). Item 0 is the time stamp the challenge was first redeemed, item 1 is the time stamp of the next redemption,
          and so on.
        readOnly: true
        type: array
        items:
          type: string
          format: date-time
          readOnly: true
      code:
        description: >-
          An optional authentication code which is only returned in the challenge resource if both a) the platform assigned the `code` when
          [constructing the challenge](#op-createChallenge)), _and_ b) the user has successfully verified the challenge. The client must [re-fetch the
          verified challenge](#op-getChallenge) in order to access this property.
        type: string
        minLength: 16
        maxLength: 128
        readOnly: true
    type: object
    x-apiture-flattened: true
  challengeState:
    title: Challenge States (v1.0.0)
    description: |
      The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators.

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

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

      <tr>
          <td><strong><code>pending</code></strong></td><td>Pending: The challenge is created but not yet started.</td>
          </tr>
      <tr>
          <td><strong><code>started</code></strong></td><td>Started: The user has started the challenge and associated authenticator(s).</td>
          </tr>
      <tr>
          <td><strong><code>verified</code></strong></td><td>Verified: The user correctly verified the corresponding authenticator(s), marking the challenge as verified.</td>
          </tr>
      <tr>
          <td><strong><code>failed</code></strong></td><td>Failed: The challenge has failed, often because the user failed one or more of the authenticators.</td>
          </tr>
      <tr>
          <td><strong><code>redeemed</code></strong></td><td>Redeemed: The user has redeemed (used) the challenge.</td>
          </tr>
      <tr>
          <td><strong><code>expired</code></strong></td><td>Expired: The challenge has expired without being verified.</td>
          </tr>
      </table>
    x-apiture-enum: challengeState
    type: string
    enum:
      - pending
      - started
      - verified
      - failed
      - redeemed
      - expired
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  authenticatorState:
    title: Authenticator State (v1.0.0)
    description: |
      The state of a challenge authenticator resource.

        * The `startAuthenticator` operation (link `apiture:start`) changes the state
          from `pending` to `started`.
        * The `retryAuthenticator` operation (link `apiture:retry`) changes the state
          to `started` and is only allowed if the authenticator has more retries available.
        * The `verifyAuthenticator` operation (link `apiture:verify`) validates
          the `attributes` and changes the state
          to `verified` if valid or
          to `failed` if invalid.

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

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

      <tr>
          <td><strong><code>pending</code></strong></td><td>Pending: The authenticator is created but not yet started.</td>
          </tr>
      <tr>
          <td><strong><code>started</code></strong></td><td>Started: The user has started the authenticator.</td>
          </tr>
      <tr>
          <td><strong><code>verified</code></strong></td><td>Verified: The user corresponding verified the authenticator.</td>
          </tr>
      <tr>
          <td><strong><code>failed</code></strong></td><td>Failed: The user failed the authenticators criteria.</td>
          </tr>
      <tr>
          <td><strong><code>expired</code></strong></td><td>Expired: The authenticator expired before the user completed the criteria.</td>
          </tr>
      </table>
    x-apiture-enum: authenticatorState
    type: string
    enum:
      - pending
      - started
      - verified
      - failed
      - expired
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  challenges:
    title: Challenge Collection (v1.0.0)
    description: |-
      Collection of challenges. The items in the collection are ordered in the `_embedded.items` array; the `name` is `challenges`.
       The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)
    example:
      _profile: 'https://api.apiture.com/schemas/challenges/challenges/v1.0.0/profile.json'
      start: 10
      limit: 10
      count: 67
      name: challenges
      _links:
        self:
          href: /auth/challenges?start=10&limit=10
        first:
          href: /auth/challenges?start=0&limit=10
        next:
          href: /auth/challenges?start=20&limit=10
        collection:
          href: /auth/challenges
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: 'https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json'
            _links:
              self:
                href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c
          - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
            _profile: 'https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json'
            _links:
              self:
                href: /auth/challenges/d62c0701-0d74-4836-83f9-ebf3709442ea
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/collection'
      - 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.'
        $ref: '#/definitions/links'
      _embedded:
        type: object
        description: Embedded objects.
        properties:
          items:
            description: An array containing a page of challenge items.
            type: array
            items:
              $ref: '#/definitions/summaryChallenge'
      _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: '#/definitions/error'
      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
    type: object
    x-apiture-flattened: true
  authenticatorCategory:
    title: authenticatorCategory (v1.0.0)
    description: |
      Categories which help classify and organize different authenticator types:
        * `knowledge` - Something you know, such as a password or
        answers to personal questions.
        * `biometric` - Something you are, such as
        facial recognition or fingerprints.
        * `device` - Something you have, such as a mobile phone
        (for confirmation via a code sent via text message) or an electronic key.

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

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

      <tr>
          <td><strong><code>knowledge</code></strong></td><td>Knowledge: Authenticate with information the user knows, such as a password or answers to personal questions.</td>
          </tr>
      <tr>
          <td><strong><code>biometric</code></strong></td><td>Biometric: Authenticate with physical characteristics of the user, such as fingerprints, voiceprint, or faceprint.</td>
          </tr>
      <tr>
          <td><strong><code>device</code></strong></td><td>Device: Authenticate with a device that the user has, such as a mobile phone or an electronic key.</td>
          </tr>
      </table>
    x-apiture-enum: authenticatorCategory
    type: string
    enum:
      - knowledge
      - biometric
      - device
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  authenticatorTypes:
    title: Authenticator types (v1.0.0)
    description: >-
      A set of methods by which a user can authenticate in order to verify their identity. The `type` property of an `authentication` must match one
      of the keys in this object. The keys in this object are names of the authenticators.
    additionalProperties:
      $ref: '#/definitions/authenticatorType'
    example:
      sms:
        name: sms
        label: SMS code
        description: Enter a code sent via SMS to the user's preferred mobile device.
        category: device
        schema:
          title: SMS attributes
          description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
          type: object
          required:
            - code
            - length
          properties:
            code:
              type: string
              description: >-
                A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to
                that. The length of the code (the number of characters or digits) must equal the `length'.
              minLength: 3
              maxLength: 10
            length:
              description: The number of digits/characters that are sent to the user via SMS.
              type: integer
              minimum: 3
              maximum: 10
              example: 6
      email:
        name: email
        label: Email code
        description: Enter a code sent via email to the user's preferred email address.
        category: device
        schema:
          title: Email attributes
          description: Schema for an authenticator's `attributes` when the authenticator type is `email`.
          type: object
          required:
            - code
            - length
          properties:
            code:
              type: string
              description: >-
                A code that was sent to the user's preferred email address. The user should enter the code in the app, then set `attributes.code` to
                that. The length of the code (the number of characters or digits) must equal the `length'.
              minLength: 3
              maxLength: 10
            length:
              description: The number of digits/characters that are sent to the user via email.
              type: integer
              minimum: 3
              maximum: 10
              example: 6
    x-apiture-version: 1.0.0
    type: object
    properties: {}
    x-apiture-flattened: true
  authenticatorType:
    title: Authenticator Type (v1.0.0)
    description: An authenticator type description.
    properties:
      name:
        type: string
        description: The name of this authenticator; also the key in the `authenticatorTypes` object.
        example: sms
      label:
        type: string
        description: A localized label or title which may be used labels or other UI controls which present a value.
        example: SMS code
      description:
        type: string
        description: A more detailed localized description of an authenticator type.
      language:
        type: string
        description: >-
          The actual natural language tag to which this authentication type description is associated, as per [RFC
          7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1). If omitted, this serves as the _default_.
        example: en-us
      category:
        type: string
        description: The authentication category.
        allOf:
          - $ref: '#/definitions/authenticatorCategory'
      schema:
        type: object
        description: >-
          The JSON schema which describe the `attributes` object for all authenticators of this type. For example, for `sms`, the schema defines a
          required `code` string.
    example:
      name: sms
      label: SMS code
      description: Enter a code sent via SMS to the user's preferred mobile device.
      category: device
      schema:
        title: SMS attributes
        description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
        type: object
        required:
          - code
          - length
        properties:
          code:
            type: string
            description: >-
              A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that.
              The length of the code (the number of characters or digits) must equal the `length'.
            minLength: 3
            maxLength: 10
          length:
            description: The number of digits/characters that are sent to the user via SMS.
            type: integer
            minimum: 3
            maximum: 10
            example: 6
    x-apiture-version: 1.0.0
    type: object
    x-apiture-flattened: true
  challengeErrorResponse:
    title: Challenge Error Response (v1.0.0)
    description: >-
      When an operation requires an additional identity verification challenge, it returns a 401 Unauthorized response status code and an error
      response with a challenge resource embedded in the `_error._embedded.challenge`. This informs the caller that they should verify the challenge
      via one or more of its `authenticators`, then retry the operation with the `Apiture-Challenge` header that references the challenge's `_id`.
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/errorResponse'
      - 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.'
        $ref: '#/definitions/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: The description of the error.
        type: object
        allOf:
          - $ref: '#/definitions/challengeError'
    type: object
    x-apiture-flattened: true
  challengeError:
    title: Challenge Error (v1.0.0)
    description: The operation error description with an embedded identity challenge.
    type: object
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/error'
      - properties:
          - _embedded
    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: '#/definitions/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: '#/definitions/error'
      _links:
        $ref: '#/definitions/links'
      _embedded:
        description: Embedded objects
        type: object
        properties:
          challenge:
            description: The details of the identity verification challenge.
            allOf:
              - $ref: '#/definitions/challenge'
    x-apiture-flattened: true
  userConfirmation:
    title: User Confirmation Request (v1.0.0)
    description: User data which confirms a customer has a banking account at the financial institution. The service does not persist this data.
    required:
      - firstName
      - lastName
      - birthdate
      - taxId
    example:
      _profile: 'https://api.apiture.com/schemas/users/userConfirmation/v1.0.0/model.json'
      firstName: John
      lastName: Smith
      birthdate: {}
      taxId: 112-22-3333
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - firstName
          - lastName
          - birthdate
          - taxId
    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.'
        $ref: '#/definitions/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
      firstName:
        description: The person's first name (or given name).
        type: string
      lastName:
        description: The person's last name (or surname).
        type: string
      birthdate:
        description: The contact's birth date in `YYYY-MM-DD` format.
        type: string
        format: date
      taxId:
        description: Official government identification (tax ID) for this person.
        type: string
        x-apiture-pii: true
        maxLength: 16
    type: object
    x-apiture-flattened: true
  userConfirmationResponse:
    title: User Confirmation Response (v1.0.0)
    description: >
      Response from confirming a user within the platform. If the request was well formed, the response contain a [Challenge](#schema-challenge)'s
      resource with one or more [`authenticators`](schema-authenticator). The client should start one of the challenge's authenticators, and after
      verifying the chosen authenticator, the client should pass the value of the challenge's `_id` as the `Apiture-Challenge` header on the
      [createUsername](#op-createUsername) operation which requires an identity challenge/verification. This response does not confirm or deny that
      the customer exists.


      If the request was ill-formed, the `_error` describes the problem.



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


      Response and request bodies using this <strong><code>userConfirmationResponse</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-createUsername'><strong><code>apiture:createUsername</code></strong></a></td><td>Assign a username for a new digital banking
      platform user</td><td><code>POST</code></td>

      </tr>

      </table>
    x-apiture-links:
      - rel: 'apiture:createUsername'
        operationId: createUsername
    example:
      _profile: 'https://api.apiture.com/schemas/users/userConfirmationResponse/v1.0.0/model.json'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - properties:
          - challenge
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      challenge:
        description: A Challenge resource.
        allOf:
          - $ref: '#/definitions/challenge'
    type: object
    x-apiture-flattened: true
  userSessionStart:
    title: User Session Start (v1.0.0)
    description: Client information for starting the new user session. The request should include the `mobileDevice` object if the client is a mobile device.
    example:
      _profile: 'https://api.apiture.com/auth/userSessionStart/v1.0.0/model.json'
      mfa:
        performed: true
        tryCount: 1
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractRequest'
      - properties:
          - mobileDevice
          - mfa
    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.'
        $ref: '#/definitions/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
      mobileDevice:
        description: 'Information about the mobile device, if the user session is from a native mobile application.'
        allOf:
          - $ref: '#/definitions/mobileDevice'
      mfa:
        description: Information related to the multi-factor authentication used to validate the user's login.
        allOf:
          - $ref: '#/definitions/startSessionMfa'
    type: object
    x-apiture-flattened: true
  startSessionMfa:
    title: Start Session MFA (v1.0.0)
    description: Information related to the multi-factor authentication used to verify the user's log in.
    type: object
    required:
      - performed
    properties:
      performed:
        description: >-
          If `true`, the client participated in and completed the MFA flow. If `false`, the log in either did not require MFA, or it performed the MFA
          flow such that the client was unaware of it.
        type: boolean
      tryCount:
        description: The number of times the user tried to authenticate with MFA for this session. This value only applies if `performed` is `true`.
        type: integer
        minimum: 0
        example: 1
    example:
      performed: true
      tryCount: 1
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  mobileDevice:
    title: Mobile Device (v1.0.0)
    description: 'Information about the mobile device, if the user session is from a native mobile application.'
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/commonDeviceFields'
      - properties:
          - gpsCoordinates
          - compromised
          - clientApplicationVersion
          - operatingSystemVersion
    properties:
      _id:
        description: The device unique identifier.
        readOnly: true
        type: string
      operatingSystem:
        type: string
        description: >-
          The operating system of the device, if known. iOS, Android, macOS, Windows, Linux are examples. An empty or omitted value indicates the
          value could not be determined.
        readOnly: true
        maxLength: 16
      vendor:
        type: string
        description: >-
          The vendor of the device, if known. Apple, Google, Samsung, LG are examples. An empty or omitted value indicates the value could not be
          determined.
        readOnly: true
        maxLength: 16
      secondaryId:
        description: 'An additional unique host-defined device identifier, for example a unique ID for advertising or other purposes.'
        type: string
      gpsCoordinates:
        description: >-
          The GPS coordinates at the time the request is made. This may be blank if the user has not granted the application access to the device GPS
          or the device does not have GPS. The format is "lat,long" where each of `latitude` and `longitude`
        allOf:
          - $ref: '#/definitions/gpsCoordinates'
      compromised:
        description: 'Indicates if device analysis shows the device may be compromised, such as rooted or jailbroken.'
        type: boolean
      clientApplicationVersion:
        description: The version of the client application.
        type: string
      operatingSystemVersion:
        description: The version of the device's native operating system
        type: string
    type: object
    x-apiture-flattened: true
  gpsCoordinates:
    title: GPS Coordinates (v1.0.0)
    type: object
    description: 'Map coordinates (latitudes, longitude) of a geographical point.'
    required:
      - longitude
      - latitude
    properties:
      latitude:
        description: Latitude of a geographical point on the map. Represented in decimal notation.
        type: number
        minimum: -90
        maximum: 90
        example: -77.9041
      longitude:
        description: Longitude of a geographical point on the map. Represented in decimal notation.
        type: number
        minimum: -180
        maximum: 180
        example: 34.2006
    example:
      latitude: -77.9041
      longitude: 34.2006
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  userSession:
    title: User Session (v1.0.0)
    description: >
      A user session. This representation contains links to continued the user session (`POST`) or end this user session (`POST`); the request and
      response body for both is a `userSession' object.



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


      Response and request bodies using this <strong><code>userSession</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-continueUserSession'><strong><code>apiture:continueUserSession</code></strong></a></td><td>continueUserSession</td><td><code>POST</code></td>

      </tr>


      <tr>

      <td><a href='#op-endUserSession'><strong><code>apiture:endUserSession</code></strong></a></td><td>endUserSession</td><td><code>POST</code></td>

      </tr>

      </table>
    example:
      _profile: 'https://api.apiture.com/auth/userSession/v1.0.0/model.json'
      _id: f2059c7a-bd6f-48d8-bb10-513e575a40a7
    x-apiture-links:
      - rel: 'apiture:continueUserSession'
        operationId: continueUserSession
      - rel: 'apiture:endUserSession'
        operationId: endUserSession
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - properties:
          - _id
    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.'
        $ref: '#/definitions/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: '#/definitions/error'
      _id:
        description: The user session identifier.
        type: string
    type: object
    x-apiture-flattened: true
  encryptionKeys:
    title: Encryption Keys
    description: >-
      A set of rotating public encryption keys that the client may use to encrypt sensitive or secret data before sending it to the service. The
      client only has access to the public key and only the service can decrypt the data. Such keys typically expire after several minutes.
    type: object
    example:
      _profile: 'https://production.api.apiture.com/schemas/common/encryptionKeys/v1.0.0/model.json'
      keys:
        pii:
          name: sensitive
          publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAwh8kIf3rM4FtehDl+WM1egDdxccXFLNPBUvgpbAISnEh373M4vdN...\n-----END RSA PUBLIC KEY-----'
          alias: sensitive-47839398
          createdAt: '2020-03-09T05:01:16.375Z'
          expiresAt: '2020-03-09T05:01:53.375Z'
        secret:
          name: secret
          publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\n-----END RSA PUBLIC KEY-----'
          alias: secret-48729783
          createdAt: '2020-03-09T05:01:16.375Z'
          expiresAt: '2020-03-09T05:01:53.375Z'
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKeys/v1.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-version: 1.0.0
    x-apiture-composition:
      - properties:
          - keys
      - $ref: '#/definitions/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.'
        $ref: '#/definitions/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: '#/definitions/error'
      keys:
        description: A map of encryption keys. The map's keys are the key `name`; the values are encryption key objects.
        type: object
        x-apiture-key: keyName
        additionalProperties:
          $ref: '#/definitions/encryptionKey'
    x-apiture-flattened: true
  root:
    x-apiture-version: 2.0.0
    title: API Root
    description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
    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: '#/definitions/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.'
        $ref: '#/definitions/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: '#/definitions/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
  errorResponse:
    x-apiture-version: 2.0.0
    title: Error Response
    description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
    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: '#/definitions/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.'
        $ref: '#/definitions/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: '#/definitions/error'
    type: object
    x-apiture-flattened: true
  abstractRequest:
    x-apiture-version: 2.0.0
    title: Abstract Request
    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`.
    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.'
        $ref: '#/definitions/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: '{uri of resource profile.json}'
      _links:
        self:
          href: '{uri of current resource}'
    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
  abstractResource:
    x-apiture-version: 2.0.0
    title: Abstract Resource
    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`.
    example:
      _profile: '{uri of resource profile.json}'
      _links:
        self:
          href: '{uri of current resource}'
    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: '#/definitions/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.'
        $ref: '#/definitions/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: '#/definitions/error'
    type: object
    x-apiture-flattened: true
  encryptionMetadata:
    title: Enryption Metadata
    description: |-
      Metadata about encrypted data within a JSON object in a request body.
      This `_encryption` object is a peer of the encrypted data.
      Each nested object that contains encrypted properties
      has it's own `_encryption` object.


      This object is a map of `string` &rarr; `string`.
      The keys are names of the encrypted property; each value is the `alias` of the
      rotating public encryption key that the client used to encrypt the named property.
      For example, for the original request body payload below,
      the client encrypts the `password` properties with the `secret` key
      and the `hint` properties with the `sensitive` key.

      <code>{</code><br>
      <code>&nbsp;&nbsp;"old" : { </code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"password": "noise-tube-branch-4183",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"hint": "bang nano twig ext",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"effectiveAt" : "2020-01-09T050:00.00Z"</code><br>
      <code>&nbsp;&nbsp;},</code><br>
      <code>&nbsp;&nbsp;"new" : { </code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"password": "mile-leave-began-9315",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"hint": "1600 take-your ",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"effectiveAt" : "2020-03-09T08:00:00.000Z"</code><br>
      <code>&nbsp;&nbsp;},</code><br>
      <code>&nbsp; "reason" : "I forgot my password"</code><br>
      <code>}</code>

      At the time of the encryption, the `secret` key has the alias `secret-48729783`
      and the `sensitive` key has the alias `sensitive-47839398`, so the `_encryption`
      metadata shows those aliases for the `password` and `hint` properties.
      Other data is not encrypted.

      <code>{</code><br>
      <code>&nbsp;&nbsp;"old": { </code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"password": "E389478492",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"hint": "E487903092478",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"effectiveAt" : "2020-01-09T050:00.00Z",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"_encryption": {</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"password" : "secret-48729783",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"hint" : "sensitive-47839398"</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;}</code><br>
      <code>&nbsp;&nbsp;},</code><br>
      <code>&nbsp;&nbsp;"new": { </code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"password": "E320480203",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"hint": "E489229004",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"effectiveAt" : "2020-03-09T08:00:00.000Z"</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;"_encryption": {</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"password" : "secret-48729783",</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"hint" : "sensitive-47839398"</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;}</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><br>
      <code>&nbsp;&nbsp;"reason" : "I forgot my password"</code><br>
      <code>}</code>

      For brevity, the encrypted data is represented as `"Ennnn"` but in reality,
      encrypted data will be longer ASCII data.
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionMetadata/v1.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-version: 1.0.0
    type: object
    properties: {}
    x-apiture-flattened: true
  collection:
    x-apiture-version: 2.0.0
    title: Collection
    description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-composition:
      - $ref: '#/definitions/abstractResource'
      - properties:
          - count
          - 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.'
        $ref: '#/definitions/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: '#/definitions/error'
      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
    type: object
    x-apiture-flattened: true
  error:
    x-apiture-version: 2.0.0
    title: Error
    description: Describes an error in an API request or in a service called via the API.
    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: '#/definitions/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: '#/definitions/error'
      _links:
        $ref: '#/definitions/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
  links:
    title: Links
    description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
    type: object
    x-apiture-key: linkRelationName
    additionalProperties:
      $ref: '#/definitions/link'
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-version: 1.0.0
    properties: {}
    x-apiture-flattened: true
  encryptionKey:
    title: Encryption Key
    description: A rotating public encryption key.
    type: object
    properties:
      name:
        description: >-
          The name of an encryption key; this identifies the type of data the key encrypts, such as `pii` for personally identifying information,
          `secret` for passwords or other secret data. The type name is chosen by the client when requesting encryption keys.
        $ref: '#/definitions/encryptionKeyName'
      publicKey:
        description: >-
          The ASCII encoded public encryption key that the client uses to encrypt data. This is half of the asymmetric public/private key pair. This
          is a mult-line string with key bopokends and embedded line breaks.
        type: string
      alias:
        description: >-
          An alias or proxy for the actual rotating key. Keys rotate every few minutes. The alias identifies a specific active public/private key
          pair. This alias should be used in the `_encryption` metadata (see [`encryptionMetadata`](#schema-encryptionMetadata)). The value of the
          alias is the concatenation of the `name`, a dash `-`, and some additional characters which identify the specific key rotation.
        type: string
        pattern: '^[a-z][a-zA-Z0-9]{2,11}-.{2,8}$'
        minLength: 6
        maxLength: 19
        example: secret-48729783
      createdAt:
        description: 'The date-time when the encryption key was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time format.'
        type: string
        format: date-time
        example: '2020-03-09T05:01:16.375Z'
      expiresAt:
        description: >-
          The date-time when the encryption key will expire. If this expiration time has passed or is less than 60 seconds away, the client should
          fetch updated encryption keys. [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time format.
        type: string
        format: date-time
        example: '2020-03-09T05:01:16.375Z'
    example:
      name: secret
      publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\n-----END RSA PUBLIC KEY-----'
      alias: secret-48729783
      createdAt: '2020-03-09T05:01:16.375Z'
      expiresAt: '2020-03-09T05:01:53.375Z'
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKey/v1.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
  link:
    x-apiture-version: 1.0.0
    title: Link
    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.
    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: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
      title: Applicant
    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
    description: The data associated with this attribute.
    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
  encryptionKeyName:
    title: Encryption Key Name
    description: >-
      An encryption key name identifies the type of data that the client wishes to encrypt, such as `pii` for personally identifying information,
      `secret` for passwords or other secret data. The type name is chosen by the client when requesting encryption keys.
    type: string
    minLength: 3
    maxLength: 10
    pattern: '^[a-z][a-zA-Z0-9]{2,9}$'
    example: secret
    x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKeyName/v1.0.0/model.json'
    x-apiture-namespace: common
    x-apiture-version: 1.0.0
    x-apiture-flattened: true
x-apiture-errors:
  accountAlreadyConfirmed:
    description: A user has already confirmed this login account
    remediation: Your login account is ready for use. You can login or use the Forgot Password option if you have forgotten your username
  getTokenAccessDenied:
    description: The client is not authorized to generate this token
    remediation: Make sure the client credentials are valid
  invalidGrant:
    description: The provided code is not valid
    remediation: Check the provided code
  postTokenAccessDenied:
    description: The client is not authorized to generate this token
    remediation: Make sure the client is authorized
  invalidSymbolForNonEmailUsernameFormat:
    description: Username cannot contain the ‘@’ symbol
    remediation: Choose a new username without the ‘@’ symbol
  usernameRequestConflict:
    description: There was a conflict requesting the username.
    remediation: Make sure the supplied information is correct.
  invalidUsernameRequest:
    description: The username request was not processed
    remediation: Check that the user exists and that the attributes match the request
  invalidNewPassword:
    description: The new password is not valid
    remediation: Check that the new password conforms to password policy
  dataNotEncrypted:
    description: The data in request was not encrypted or it was encrypted with obsolete keys
    remediation: Encrypt the data using valid encryption keys
  invalidUsername:
    description: 'For your security, we recommend choosing a more complex username with at least one special character.'
    remediation: 'Choose a new username that satisfies the financial institution''s policies or is more complex, such as including special characters.'
    attributes:
      properties:
        specialCharacters:
          description: A string containing recommended special characters.
          type: string
  challengedNotVerified:
    description: 'The challenge has not been verified, has expired, or has been redeemed too many times'
    remediation: Pass a valid and verified challenge resource in the Apiture-Challenge request header
  accessDenied:
    description: The credentials supplied in the request are insufficient to grant access
    remediation: Check the supplied credentials for validity
  currentPasswordDoesNotMatch:
    description: The current password does not match
    remediation: Check that the current password in the request match the user's current password
  noSuchUser:
    description: No users were found for the specified userId
    remediation: Ensure the supplied userId corresponds to an Apiture user
  challengeNotFound:
    description: No Challenge was found for the specified challengeId
    remediation: Ensure the supplied challengeId corresponds to a valid challenge resource
  authenticatorNotFound:
    description: No authenticators were found for the specified authenticatorId and challengeId combination
    remediation: Ensure the supplied authenticatorId corresponds to a valid authenticator resource
  noSuchDevice:
    description: No devices were found for the specified userId
    remediation: Verify that the device exists for the user and resubmit
  invalidAuthenticatorState:
    description: The operation is not allowed from the authenticator’s current state
    remediation: Ensure the supplied authenticatorId corresponds to an Apiture authenticator resource in the correct state
    attributes:
      properties:
        currentState:
          type: string
        allowedStates:
          type: array
          items: string
          minLength: 1
  authenticatorAttemptsExceeded:
    description: User has exceeded the allowed number of retry attempts.
    remediation: Consider locking this user or device in order to prevent fraud.
    attributes:
      properties:
        authenticatorId:
          type: string
        maximumRetries:
          type: number
        retryCount:
          type: number
  authenticatorTypeInUse:
    description: An update to the authenticator types omits one or more types that are in use.
    remediation: Include all in-use type names
    attributes:
      properties:
        typeNames:
          description: The list of authenticator types that are in use but missing from the request.
          type: array
          items: string
          example:
            - sms
            - email
  redeemChallengeConflict:
    description: >-
      No `Apiture-Challenge` request header was passed when expected, or the challenge has not been verified, has expired, or has been redeemed too
      many times.
    remediation: Ensure the supplied challengeId corresponds to a valid challenge resource
  authenticatorNotCompletable:
    description: The authenticator is not in a state that allows completing.
    remediation: 'Only verify an authenticator if the `apiture:verify` link exists.'
  invalidAuthenticatorAttributes:
    description: The `attributes` in the authenticator do not conform to the schema for the authenticator type.
    remediation: Pass `attributes` that satisfy the JSON schema for the authenticator's type.
  invalidSession:
    description: No session was found
    remediation: Resubmit request with a valid session
  challengeRefNotFound:
    description: There is no challence resource corresponding to the referenced challenge
    remediation: Pass a reference to a valid challence resource
  authenticatorRefNotFound:
    description: There is no authentictor resource corresponding to the referenced authentictor
    remediation: Pass a reference to a valid authentictor resource
  missingApitureChallengeHeader:
    description: The Apiture-Challenge request header is missing
    remediation: Pass a reference to a valid challence resource in the Apiture-Challenge header
  challengedAlreadyRedeemed:
    description: The challenge resource has already been redeemed
    remediation: Use the most recently issued challenge
  challengedExpired:
    description: The challenge resource has expired
    remediation: Use the most recently issued challenge and complete the authenticators before the challenge expires
  postTokenForbidden:
    description: The client is not authorized to generate a new token
    remediation: Use the most recently issued challenge
x-apiture-traits:
  - api:
      links:
        - getMetadata
        - authorize
        - getToken
        - refreshToken
        - getDevices
        - getChallenges
        - createChallenge
        - getAuthenticatorTypes
        - updateAuthenticatorTypes
        - getEncryptionKeys
        - getApi
        - getApiDoc
      applied: true
  - resource:
      name: challenge
      description: Identity challenge.
      excludeMethods:
        - put
        - patch
      applied: true
  - resource:
      name: authenticator
      description: Identity verification method.
      excludeMethods:
        - put
        - patch
      pathPrefix: '/challenges/{challengeId/'
      applied: true
  - state:
      name: authenticator
      state: started
      verb: start
      applied: true
  - state:
      name: authenticator
      state: retried
      verb: retry
      applied: true
  - state:
      name: authenticator
      state: redeemed
      verb: redeem
      applied: true
  - security:
      baseScope: profiles
      applied: true
x-apiture-annotated-at: '2020-05-28T16:34:32.590Z'
host: api.devbank.apiture.com
