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. ThetppConsent
will be false for connections usingexpirationDateTime
. 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 eithermonthsInitialConsent
ordaysInitialConsent
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"
}
}
}
}
Default consent behaviour
transactionFromDateTime
- When transactionFromDateTime
is not specified, if the banking provider gives us information on how far back they can go for transactions (shown in monthsInitialConsent/daysInitialConsent
), we will either go the full length they provide, or 36 months by default (which ever is shortest). For example:
- First Direct allows to get 72 months of transactions, so in this case we will get 36 months of transactions
- Barclays allows us to get 24 months of transactions, so in this case, we will get 24 months of transactions,
- American Express allows us to get 89 days worth of data, so we only attempt 89 days of transactions in this case.
If both monthsInitialConsent
and daysInitialConsent
are null, we default to attempting to retrieve 12 months of transaction data.
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"
]
}
}
}
}
Default Permissions
When requesting account access, our standard practice includes seeking consent for a set of default permissions required to efficiently manage transactions and account details. The following permissions are automatically requested unless specifically replaced or modified:
- 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 account identification details. Requires at least one of
ReadTransactionsCredits
orReadTransactionsDebits
to be present in the permissions array. - ReadTransactionsCredits: permission will grant access to credit transactions.
- ReadTransactionsDebits: permission will grant access to debit transactions.
- ReadProducts: permission will grant access to read all production information related to the account.
Replacing permissions
In scenarios where the default permissions do not meet your particular needs, you can specify alternative permissions. This can be done by using the replace action in the permissionsAction field of the mh:consent
claim. This allows the explicit definition of which permissions to apply for the account information request.
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"]
})
Updated 7 months ago