Customer Consent

Introduction

After successfully registering with Mettle, the TPP requires consent from the customer to access their account. A consent is an agreement between the TPP as the application owner and the customer.

As a TPP, once consent is agreed between you and the customer, your client application initiates the request for access to the customer's data. The customer confirms or declines the request on the Mettle mobile application, using strong customer authentication.

The design of the API ensures that a customer's credentials are never shared with you, so they can be reassured that their credentials remain confidential at all times.

Making Requests

Each request must be made using your 'Transport' certificate.

Once you have an access_token it must be passed as the Bearer Authorization header to every request.

The Process

The process of gaining access to a customer's data is a multi-step process, all of which must be completed.

Step 1. Obtaining an Access Token

Firstly, you authenticate with us using the token endpoint and grant_type=client_credentials to obtain an access_token. See the OAuth API documentation for full details.

When requesting an access_token you must pass one or more of the scopes you have been granted.

The request must include the client_id provided on registration.

Step 2. Registering an Access Request

Once you have an access_token, you may make a POST request to one of the *-consents endpoints to register your intent to access customer data.

This request contains details of the type of access you wish to obtain and will return a ConsentId. See the PSD2 API documentation for full details.

At this stage the Access Request is in the AwaitingAuthorisation state. It cannot be used until it is confirmed by the customer.

Step 3. Confirming the Access Request

The next step is to obtain confirmation from the customer for your Access Request.

To achieve this you must redirect the customer to our mobile application via the authorize endpoint (See the OAuth API documentation) with the following request parameters:

Name	Value
client_id	Provided on registration
response_type	code%20id_token
request	A JWS (signed JWT) detailed below - Try it in jwt.io

Header

{
  "alg": "PS256",
  "kid": "<The key ID of your 'Signature' key>",
  "typ": "JWT"
}

Payload

{
  "aud":  "0015800000jfwxXAAQ",
  "exp": <Timestamp of when this JWT will expire>,
  "client_id": "<Provided on registration>",
  "response_type": "code id_token",
  "state": "<Some random string passed through by us so you can verify>",
  "nonce": "<Some random string passed through by us so you can verify>",
  "scope": "<Must match the scope you asked for when requesting the Access Token>",
  "redirect_uri": "<Must be on of the redirect_uris you provided when registering>",
  "claims": {
    "id_token" : {
      "openbanking_intent_id": {
        "value": "<The ConsentId returned from Access Request>"
      }
    }
  }
}

Signature

Your 'Signature' public and private keys.

The customer will be taken directly into the Mettle application or they will be presented with a QR code that they can use to access their Mettle application.

The customer will log in using their credentials, view your Access Request and confirm or decline it.

Step 4. Confirm or Decline

The customer has the choice to confirm or decline your Access Request.

If they confirm, the Access Request is put into the Authorised state. If the customer declines, it is put into the Rejected state.

Either way, the customer is redirected back to you using the redirect_uri you gave in the request.

Step 5. Authorisation Endpoint Response

If the customer confirms the Access Request, the customer is redirected back to you with both a code and an id_token provided as a hash fragment of that redirect.

To remain FAPI compliant you must verify the signature of the id_token using the public key available from our JWKS endpoint which can be found in the jwks_uri attribute from the .well-known endpoint.

Step 6. Exchanging an Authorisation Code for an Access Token

In this step you exchange the code for an access_token by using the token endpoint and grant_type=authorization_code. See the OAuth API documentation for full details.

This access_token has fixed validity, but you can use the refresh_token (also returned in the response) to obtain a new one once it expires.

Step 7. Accessing Customer Data

Now you have the access_token, you may access the customer's data via the APIs which pertain to the scope for which access was granted. See the PSD2 API documentation for full details.

The access_token must be passed as the Bearer Authorization header to any request.

Access Validity Period

The access_token is only valid for 5 minutes. Once it has expired you can obtain a new one using your refresh_token.

You can do this by using the token endpoint and grant_type=refresh_token. See the OAuth API documentation for full details.

The refresh_token is valid for 90 days. After this you must ask the customer to re-confirm if you still require access.

Note: 90 days relates only to the length of time a TPP has access to customer data. Any transactional date range the customer has confirmed can be accessed during those 90 days.