Qwist Accesses API

openapi: 3.2.0
info:
  title: nrich Accesses API
  version: '2.10'
  contact:
    name: Qwist GmbH
    email: partnersupport@qwist.com
    url: https://qwist.com
  description: This is the reference for Qwist's nrich API
servers:
- url: https://api.nrich.qwist.cloud
  description: Staging environment
tags:
- name: Accesses
paths:
  /rest/accesses:
    post:
      summary: Add provider access
      description: Attach a new provider access to the user's account. If the provider uses an authentication flow where customer credentials have to be presented, use the information from the catalog to identify available input fields. All mandatory (`is_optional=false`) public (`is_secret=false`) fields have to be provided when creating an access. All credentials that are sent with the request are securely stored in the finX backend.
      tags:
      - Accesses
      security:
      - user_auth: []
      operationId: addProviderAccess
      parameters:
      - $ref: '#/paths/~1rest~1accesses/get/parameters/0'
      - $ref: '#/paths/~1catalog/get/parameters/0'
      responses:
        '201':
          description: Provider access details.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
              - access_method_id
              properties:
                access_method_id:
                  type: string
                  format: UUID
                  example: ae441170-b726-460c-af3c-b76756de00e0
                  description: nrich ID of the provider access method.
                credentials:
                  description: Credentials used for authentication with the financial service provider.
                  oneOf:
                  - type: object
                    additionalProperties:
                      type: string
                    description: Pairs of key/value-items as specified in the access-method of the service provider's catalog entry.
                    example:
                      login_id: user.name
                      password: hunter2
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - encrypted
                      value:
                        type: string
                        description: Pairs of key/value-items as specified in the access-method of the service provider's catalog entry encrypted with JSON web encryption.
                        example: eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZDQkMtSFM1MTIifQ.aq_baOMnl2WPI7Lf..
                consent:
                  type: object
                  description: Configuration of the PSD2 consents. Is ignored for non-PSD2 accesses.
                  properties:
                    recurring:
                      type: boolean
                      default: true
                      description: Indicates whether the consent is for an ongoing use-case
                    period:
                      type: integer
                      minimum: 1
                      maximum: 180
                      default: 180
                      description: Specify the period in days for which the consent is valid. Ignored if recurring is set to false.
                    scopes:
                      type: array
                      description: 'Defines the requested consent scopes. The actual scopes granted are determined on a best-effort basis and may differ from the requested configuration depending on the capabilities and policies of the bank.

                        '
                      default:
                      - ACCOUNTS
                      - BALANCES
                      - TRANSACTIONS
                      items:
                        type: string
                        enum:
                        - ACCOUNTS
                        - BALANCES
                        - TRANSACTIONS
                        - PAYMENTS
                    accounts:
                      type: array
                      items:
                        $ref: '#/paths/~1onetime~1access/post/requestBody/content/application~1json/schema/allOf/1/properties/accounts/items'
                  required:
                  - recurring
                  - period
                  - scopes
                  - accounts
    get:
      summary: List provider accesses
      operationId: listProviderAccesses
      description: List all connected provider accesses of user.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - in: query
        name: embed
        schema:
          type: string
          example: (provider,access_method)
        description: The `embed` query parameter allows it to add additional information to the response. The format for the parameter value is a comma separated list of field names (that is optionally surrounded by parentheses). Currently supported fields to be embedded are "provider" and "access_method".
      - $ref: '#/paths/~1catalog/get/parameters/0'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - created_at
                  - access_method_id
                  - auth_methods
                  - auto_sync
                  - credential
                  - save_pin
                  - status
                  properties:
                    id:
                      $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0/schema'
                    access_method_id:
                      $ref: '#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/access_method_id'
                    consent:
                      $ref: '#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/consent'
                      deprecated: true
                      description: Will be removed in favor of `credential` in the future.
                    credential:
                      $ref: '#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/responses/200/content/application~1json/schema'
                      description: The current credential used to authenticate with the financial provider.
                    created_at:
                      description: Entity creation timestamp.
                      example: '2026-04-01T18:30:00.000+00:00'
                      type: string
                      format: date-time
                    auth_methods:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            $ref: '#/paths/~1rest~1accesses~1{access-id}~1syncs~1{sync-id}~1challenges~1{challenge-id}~1response/post/requestBody/content/application~1json/schema/oneOf/0/properties/method_id'
                          type:
                            type: string
                            description: Type of authentication method.
                            enum:
                            - SMS_OTP
                            - PUSH_OTP
                            - CHIP_OTP
                            - PHOTO_OTP
                            - DECOUPLED
                          name:
                            type: string
                            example: mobileTAN
                            description: Name of the authentication method as used by the financial provider.
                        required:
                        - id
                        - type
                        - name
                      description: List of supported methods for payment initiation and authentication.
                    selected_auth_method:
                      $ref: '#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items/properties/auth_methods/items'
                      description: 'The method that was last selected for strong customer authentication. This method will be reused for subsequent synchronization or payment initiation operations by default.

                        '
                    auto_sync:
                      type: boolean
                      description: Indicates if the access is automatically synchronized.
                      example: false
                    save_pin:
                      type: boolean
                      default: false
                      description: Indicates if the provider credentials are saved for this access.
                      example: true
                    status:
                      type: object
                      description: Synchronization status
                      properties:
                        synced_at:
                          $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                          description: Time of last synchronization.
                        succeeded_at:
                          $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                          description: Time of last successful synchronization.
                        message:
                          type: string
                          description: Human-readable error message
                      required:
                      - synced_at
                      - succeeded_at
                    provider:
                      $ref: '#/paths/~1rest~1catalog~1banks/get/responses/200/content/application~1json/schema/items/allOf/0/allOf/1'
                      description: The details of the provider associated to this access. This field is only included if the query parameter `?embed=provider` is added to the request.
                    access_method:
                      $ref: '#/paths/~1rest~1catalog~1banks/get/responses/200/content/application~1json/schema/items/allOf/0/allOf/0/properties/access_methods/items'
                      description: The details of the access method associated to this access. This field is only included if the query parameter `?embed=access_method` is added to the request.
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/accesses/{access-id}:
    get:
      summary: Get provider access
      operationId: getProviderAccess
      description: Retrieve the details of a specific provider access identified by its ID.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - name: access-id
        in: path
        required: true
        schema:
          type: string
          example: X12345.6
          description: nrich ID of the provider access.
      - $ref: '#/paths/~1rest~1accesses/get/parameters/0'
      - $ref: '#/paths/~1catalog/get/parameters/0'
      responses:
        '200':
          $ref: '#/paths/~1rest~1accesses/post/responses/201'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
    delete:
      summary: Delete provider access
      operationId: deleteProviderAccess
      description: Delete a specific provider access identified by its ID.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      responses:
        '204':
          $ref: '#/paths/~1rest~1user/delete/responses/204'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
  /rest/accesses/{access-id}/credentials:
    get:
      summary: List credentials
      operationId: listCredentials
      description: List all credentials that have been used to access the provider sorted by the `created_at` field. The first credential in the list is the currently active one whereas the remaining ones are either revoked or expired.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - $ref: '#/paths/~1catalog/get/parameters/0'
      responses:
        '200':
          description: List of credentials.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/responses/200/content/application~1json/schema'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
  /rest/accesses/{access-id}/credentials/{credential-id}:
    get:
      summary: Get credential
      operationId: getCredential
      description: Retrieve the details of a specific credential of a provider access identified by its ID.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - name: credential-id
        in: path
        required: true
        schema:
          type: string
          format: UUID
          example: ae441170-b726-460c-af3c-b76756de00e0
          description: UUID of the credential.
      - $ref: '#/paths/~1catalog/get/parameters/0'
      responses:
        '200':
          description: Credential details.
          content:
            application/json:
              schema:
                type: object
                description: Customer credentials attached to the access.
                properties:
                  id:
                    $ref: '#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/parameters/1/schema'
                  type:
                    type: string
                    description: 'Type of the credential.

                      * BASIC: username/password pair

                      * CONSENT: PSD2 consent configuration as confirmed by the bank

                      * OAUTH: OAuth2 token'
                    enum:
                    - BASIC
                    - CONSENT
                    - OAUTH
                    example: CONSENT
                  status:
                    type: string
                    description: Validity status of the credential.
                    enum:
                    - ACTIVE
                    - REVOKED
                    - EXPIRED
                    - PENDING
                  config:
                    description: Configuration of the consent as returned by the financial provider.
                    $ref: '#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/consent'
                  created_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Credential creation timestamp.
                    example: '2023-08-31T00:00:00.000Z'
                  expires_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Credential expiration timestamp. Only applicable for credentials of type `CONSENT` and `OAUTH`.
                    example: '2023-08-31T00:00:00.000Z'
                  revoked_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Credential revocation timestamp.
                    example: '2023-08-31T00:00:00.000Z'
                required:
                - id
                - type
                - status
                - created_at
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
    patch:
      summary: Revoke credential
      operationId: patchCredential
      description: Revoke a specific credential of a provider access identified by its ID. Revoking a credential of type `CONSENT` will trigger a revocation call to the financial provider. The `status` field **must** be set to `REVOKED`.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - $ref: '#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/parameters/1'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  type: string
                  description: Validity status of the credential.
                  enum:
                  - REVOKED
      responses:
        '200':
          description: Credential details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/paths/~1rest~1accesses~1{access-id}~1credentials~1{credential-id}/get/responses/200/content/application~1json/schema'
                - type: object
                  properties:
                    status:
                      example: REVOKED
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
  /rest/accesses/{access-id}/remove_pin:
    post:
      summary: Remove stored PIN
      operationId: removePINFromProviderAccess
      deprecated: true
      description: Remove a PIN from the API backend that has been previously stored for automatic synchronization or ease of use. Will be removed in favor of the `PATCH /rest/accesses/{access-id}/credentials/{credential-id}` endpoint in the future.
      tags:
      - Accesses
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      responses:
        '200':
          $ref: '#/paths/~1rest~1accesses/post/responses/201'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
components:
  securitySchemes:
    user_auth:
      type: http
      description: 'In order to access any information belonging to a user, a client has to authenticate with a token linking itself to the user.  This token is called an `access token` and contains information on the client, the user and the level of access the client has to the users data. In order to authenticate using such an access token the HTTP header `Authorization` is set to `Bearer <access token>`. The  `access token` is formatted

        as a JSON Web Token according to [RFC7519](https://tools.ietf.org/html/rfc7519)


        Such an `access token` is either returned when


        * exchanging an authorization code after a successful OAuth login flow

        * logging in with the user''s credentials

        * exchanging a refresh token, which is returned at either of the aforementioned points


        **Authentication errors**


        In case of an authentication error a HTTP code 401 response is returned containing further

        details on the kind of error in the `WWW-Authenticate` header.


        In addition to the below listed scope the flags are used for simple boolean permissions.


        | Flag            | Description                                  |

        | --              | --                                           |

        | submit_payments | Allow submission of payments to bank server  |

        | offline         | Access finX API when the user is not present |

        | create_user     | Allow creation of finX accounts              |


        **Example**


        The string `"accounts=rw submit_payments"` is URL-encoded and passed as the URL

        parameter `scope`.'
      scheme: bearer
      bearerFormat: JWT
      x-bearerInfoFunc: app.decode_token
      x-scopes:
        accounts=rw: Modify accounts
        accounts=ro: Read accounts
        balance=ro: Read account balance
        securities=ro: Read securities
        transactions=ro: Read transactions
        transactions=rw: Modify transactions
        payments=ro: Read payments
        payments=rw: Create/modify payments
        submit_payments: Submit payment to service provider
        user=ro: Read user information
        user=rw: Modify user information
    client_auth:
      x-basicInfoFunc: app.basic_auth
      type: http
      scheme: basic
      description: Client authentication is performed via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with client ID as username and client secret as password.
x-provenance:
  method: searched
  source: https://docs.qwist.com/reference
  harvested: '2026-10-21'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.qwist.com/reference/addprovideraccess.md
  - https://docs.qwist.com/reference/categorizetransactions.md
  - https://docs.qwist.com/reference/createaccesstoken.md
  - https://docs.qwist.com/reference/createaccountverification.md
  - https://docs.qwist.com/reference/createcontract.md
  - https://docs.qwist.com/reference/createincomereport.md
  - https://docs.qwist.com/reference/createmanualsync.md
  - https://docs.qwist.com/reference/createnotification.md
  - https://docs.qwist.com/reference/createonetimeaccess.md
  - https://docs.qwist.com/reference/createonetimeincomereport.md
  - https://docs.qwist.com/reference/createonetimepayment.md
  - https://docs.qwist.com/reference/createonetimeriskreport.md
  - https://docs.qwist.com/reference/createongoingaccess.md
  - https://docs.qwist.com/reference/createongoingpayment.md
  - https://docs.qwist.com/reference/createongoingriskreport.md
  - https://docs.qwist.com/reference/createpayment.md
  - https://docs.qwist.com/reference/createpaymentfromaccount.md
  - https://docs.qwist.com/reference/createqwistlink.md
  - https://docs.qwist.com/reference/createriskreport.md
  - https://docs.qwist.com/reference/createsync.md
  - https://docs.qwist.com/reference/createupload.md
  - https://docs.qwist.com/reference/createuser.md
  - https://docs.qwist.com/reference/createverifyandpay.md
  - https://docs.qwist.com/reference/deleteaccount.md
  - https://docs.qwist.com/reference/deleteclientuser.md
  - https://docs.qwist.com/reference/deletecontract.md
  - https://docs.qwist.com/reference/deletenotification.md
  - https://docs.qwist.com/reference/deletepayment.md
  - https://docs.qwist.com/reference/deleteprovideraccess.md
  - https://docs.qwist.com/reference/deleteuser.md
  - https://docs.qwist.com/reference/getaccount.md
  - https://docs.qwist.com/reference/getaccountbalance.md
  - https://docs.qwist.com/reference/getaccountverificationreceipt.md
  - https://docs.qwist.com/reference/getandgenerateincomereport.md
  - https://docs.qwist.com/reference/getartifact.md
  - https://docs.qwist.com/reference/getcategories.md
  - https://docs.qwist.com/reference/getcategoriesforaccess.md
  - https://docs.qwist.com/reference/getcategoriesforaccount.md
  - https://docs.qwist.com/reference/getcategorytree.md
  - https://docs.qwist.com/reference/getcontract.md
  - https://docs.qwist.com/reference/getcredential.md
  - https://docs.qwist.com/reference/getincomereport.md
  - https://docs.qwist.com/reference/getinsurance.md
  - https://docs.qwist.com/reference/getloan.md
  - https://docs.qwist.com/reference/getnotification.md
  - https://docs.qwist.com/reference/getpaymentchallenge.md
  - https://docs.qwist.com/reference/getpaymentchallengeofaccount.md
  - https://docs.qwist.com/reference/getpaymentinitstatus.md
  - https://docs.qwist.com/reference/getpaymentinitstatusofaccount.md
  - https://docs.qwist.com/reference/getpaymentofaccount.md
  - https://docs.qwist.com/reference/getpaymentpartners.md
  - https://docs.qwist.com/reference/getpaymentpartnersforaccess.md
  - https://docs.qwist.com/reference/getpaymentpartnersforaccount.md
  - https://docs.qwist.com/reference/getpaymentreceipt.md
  - https://docs.qwist.com/reference/getprovideraccess.md
  - https://docs.qwist.com/reference/getriskreport.md
  - https://docs.qwist.com/reference/getsecurityofaccount.md
  - https://docs.qwist.com/reference/getsyncchallenge.md
  - https://docs.qwist.com/reference/getsyncstatus.md
  - https://docs.qwist.com/reference/gettimeline.md
  - https://docs.qwist.com/reference/gettimelineforaccess.md
  - https://docs.qwist.com/reference/gettimelineforaccount.md
  - https://docs.qwist.com/reference/gettransaction.md
  - https://docs.qwist.com/reference/gettransactionofaccount.md
  - https://docs.qwist.com/reference/getuploadstatus.md
  - https://docs.qwist.com/reference/getuser.md
  - https://docs.qwist.com/reference/getversion.md
  - https://docs.qwist.com/reference/initpayment.md
  - https://docs.qwist.com/reference/initpaymentofaccount.md
  - https://docs.qwist.com/reference/listaccounts.md
  - https://docs.qwist.com/reference/listaccountsofaccess.md
  - https://docs.qwist.com/reference/listbanks.md
  - https://docs.qwist.com/reference/listcatalog.md
  - https://docs.qwist.com/reference/listcatalogclientauth.md
  - https://docs.qwist.com/reference/listclientusers.md
  - https://docs.qwist.com/reference/listcontracts.md
  - https://docs.qwist.com/reference/listcontractsofaccess.md
  - https://docs.qwist.com/reference/listcontractsofaccount.md
  - https://docs.qwist.com/reference/listcredentials.md
  - https://docs.qwist.com/reference/listinsurances.md
  - https://docs.qwist.com/reference/listinsurancesofaccess.md
  - https://docs.qwist.com/reference/listloans.md
  - https://docs.qwist.com/reference/listloansofaccess.md
  - https://docs.qwist.com/reference/listnotifications.md
  - https://docs.qwist.com/reference/listpaymentchallenges.md
  - https://docs.qwist.com/reference/listpaymentchallengesofaccount.md
  - https://docs.qwist.com/reference/listpayments.md
  - https://docs.qwist.com/reference/listpaymentsofaccount.md
  - https://docs.qwist.com/reference/listprovideraccesses.md
  - https://docs.qwist.com/reference/listsecurities.md
  - https://docs.qwist.com/reference/listsecuritiesofaccount.md
  - https://docs.qwist.com/reference/listservices.md
  - https://docs.qwist.com/reference/listsyncchallenges.md
  - https://docs.qwist.com/reference/listtransactions.md
  - https://docs.qwist.com/reference/listtransactionsofaccount.md
  - https://docs.qwist.com/reference/patchcredential.md
  - https://docs.qwist.com/reference/removepinfromprovideraccess.md
  - https://docs.qwist.com/reference/replacenotifications.md
  - https://docs.qwist.com/reference/revokeoauthtoken.md
  - https://docs.qwist.com/reference/solvepaymentchallenge.md
  - https://docs.qwist.com/reference/solvepaymentchallengeofaccount.md
  - https://docs.qwist.com/reference/solvesyncchallenge.md
  - https://docs.qwist.com/reference/updatecontract.md
  - https://docs.qwist.com/reference/updatenotification.md
  - https://docs.qwist.com/reference/updateuser.md
  merge:
    pages: 105
    deduped: 1107
    conflicts_kept_first: 0