Account Information Consent & Permissions

Consent expiration and transactions

The time for which an AIS connection consent can live for, and for how far in the past it can access transactions from can be specified as part of the mh:consent claims value.

To set these values in the claims, they need to be set in the mh:consent value in the claims, with these properties:

  • expirationDateTime - the date time at which the banking connection will expire with the banking provider (maximum 90 days in the future)
  • transactionFromDateTime - the date time at which transactions will be pulled from. The earliest time we allow for this value is the closest to the current time of these values:
    • 72 months in the past
    • The value specified for monthsInitialConsent for the given provider.

πŸ“˜

Setting expirationDateTime and reconsent

If expirationDateTime is set, this means that the connection will not be able to use the shortened reconsent journey and will have to go through full re-authentication with the provider. The tppConsent will be false for connections using expirationDateTime. Please see the guide on 90 day reconsent changes for more information.

πŸ“˜

Setting transactionFromDateTime limitations

When setting transactionFromDateTime, please be aware that some providers may have a limit on how far back transactions can be fetched. When limits are known, these will appear in the well known connections endpoint (https://identity.moneyhub.co.uk/oidc/.well-known/api-connections) in either monthsInitialConsent or daysInitialConsent

When making a connection without specifying a user ID (One time access scenario) the default time for the expiration date time will be 24 hours in the future.

{
  "id_token": {
    "sub": {
      "essential": true
    },
    "mh:con_id": {
      "essential": true
    },
    "mh:consent": {
      "essential": true,
      "value": {
        "expirationDateTime": "2022-05-02T00:00:00+00:00",
        "transactionFromDateTime": "2021-05-02T00:00:00+00:00"
      }
    }
  }
}

Additional permissions

There are some additional permissions that can be requested when connecting to an account. These should be shown on the consent page if they are being requested

ReadStandingOrdersBasic permission will grant access to basic standing order information, such as the reference, amounts and dates payments will be made.

ReadStandingOrdersDetail permission will grant access to the basic standing order information as well as the payee account information.

ReadBeneficiariesDetail permission will grant access to beneficiaries, which are payment or transfer destination accounts which have been authorized by the bank.

ReadStatementsBasic permission will grant access to basic statements.

ReadStatementsDetail permission will grant access to full statement information including amounts.

The additional permissions must be requested via the mh-consent claim along with any other claims in the following way:

{
  "id_token":{
    "mh:consent":{
      "value":{
        "permissions":[
          "ReadStandingOrdersBasic",
          "ReadBeneficiariesDetail"
        ]
      }
    }
  }
}

Replacing permissions

By default account, balance, transaction, and product permissions are used when requesting account information. In cases where you do not want to use these defaults you can replace them.

To do this you can add permissionsAction: "replace" to the mh-consent claim along with the permissions you would like to request information for.

ReadAccountsBasic permission will grant access to basic account information

ReadAccountsDetail permission will grant access to account identification details

ReadBalances permission will grant access to read all balance information

ReadTransactionsDetail permission will grant access to transaction data. Requires at least one of ReadTransactionsCredits or ReadTransactionsDebits to be present in the permissions array.

ReadProducts permission will grant access to read all production information related to the account.

Replacing permissions requires either ReadAccountsBasic or ReadAccountsDetail to be included in the permissions array.

{
  "id_token":{
    "mh:consent":{
      "value":{
        "permissions":[
          "ReadAccountsDetail"
        ],
        permissionsAction: "replace",
      }
    }
  }
}

NodeJS Library

🚧

Prerequisites

You will need v4.17.0 of the Moneyhub API Client to make use of this feature

If you use our NodeJS client library, you can make connections with these claims by specifying expirationDateTime , transactionFromDateTime and permissions in the authorisation URL generating methods.

const url = await moneyhub.getAuthorizeUrl({
  scope: "openid id:api",
  state: " your state value",
  nonce: "your nonce value",
  expirationDateTime: "2022-09-01T00:00:00.000Z",
  transactionFromDateTime: "2020-09-01T00:00:00.000Z",
  permissions: ["ReadBeneficiariesDetail"]
})