Example

This page describes an end-to-end example for a TPP invoking the Accounts APIs. The example describes the required setup and required APIs calls in order to create a consent, authorise the consent and retrieve account information. The examples are use the cURL command to invoke the APIs. The following information is required beforehand:
client id: As provided during Dynamic Client Registration
client secret: As provided during Dynamic Client Registration
Organisation ID: As assigned by the Open Banking Directory during the registration of the organisation
Open Banking Signature Key: As created by you and registered with a software statement in the Open Banking Directory.
Open Banking Signature Key ID: As assigned by the Open Banking Directory during creation of a software statement
Open Banking Transport Key: As created by you and registered with a software statement in the Open Banking Directory.
Open Banking Transport Certificate: As created by the Open Banking Directory during creation of a software statement
redirect URLs: As registered with Open Banking and used in the SSA during Dynamic Client Registration

The following information is required during the process and will become available when the authentications and authorisations have been successful:
Bearer token: obtained in the first step when the authentication is successful
nonce: a random number that should not be used twice 
consent ID: obtained in the second step when creating a consent
code: obtained in the redirect URL after the PSU has been authenticated
identity token: created in step 6
1. Authenticate

Execute the following curl command to authenticate and retrieve a bearer token:

curl -X POST https://api.mhbkemea.co.uk:446/mhbkemea/sb/confidential/oauth2/token --cert (OB_transport_certificate).pem --key (OB_transport_key).key --insecure -H Accept:application/json -d grant_type=client_credentials -d scope=accounts -d client_secret=(client_secret) -d client_id=(client_id)

Note the bearer token received in the response

2. Create Consent

Execute the following curl command to create a consent:

curl -X POST https://api.mhbkemea.co.uk:446/mhbkemea/sb/open-banking/v3.1/aisp/account-access-consents --cert (OB_transport_certificate).pem --key (OB_transport_key).key --insecure -H Content-Type:application/json -H Accept:application/json -H Authorization:"Bearer (bearer token)" -H x-fapi-financial-id:0015800001HQQt0AAH -H X-IBM-Client-Id:(client_id) -H client_id:(client_id) --data '{"Data":{"Permissions":["ReadAccountsDetail","ReadBalances","ReadTransactionsCredits","ReadTransactionsDebits","ReadTransactionsDetail"],"ExpirationDateTime":"2021-07-02T09:17:00.000Z","TransactionFromDateTime":"2001-01-22T09:41:58.441Z","TransactionToDateTime":"2032-09-05T00:47:35.714Z"},"Risk":{}}'

Note the consent ID in the response.

3. Retrieve Consent (Optional)

Execute the following curl command to lookup the consent by its id:

curl -X GET https://api.mhbkemea.co.uk:446/mhbkemea/sb/open-banking/v3.1/aisp/account-access-consents/(consent_id) --cert (OB_transport_certificate).pem --key (OB_transport_key).key --insecure -H Content-Type:application/json -H Accept:application/json -H Authorization:"Bearer (bearer token)" -H x-fapi-financial-id:0015800001HQQt0AAH -H X-IBM-Client-Id:(client_id) -H accept:application/json
4. Create JWT for OIDC Hybrid flow

Create a JWT with the following data as a preparation for the PSU Authentication. Use https://jwt.io or any JWT API of your choice in order to create and sign the token.

Header: {"kid":"(signature_key_id)","alg":"PS256"}
Payload: {"iss":"https://api.alphabank.com","aud":"s6BhdRkqt3","response_type":"code id_token","client_id":"(client_id)","redirect_uri":"(redirect_URL)","scope":"openid accounts","state":"af0ifjsldkj","nonce":"(nonce)","claims":{"userinfo":{"openbanking_intent_id":{"value":"consent id","essential":true}},"id_token":{"openbanking_intent_id":{"value":"consent id","essential":true},"acr":{"essential":true,"values":["urn:openbanking:psd2:sca","urn:openbanking:psd2:ca"]}}}}
Signature: (create using the your signature key)
 

For example: eyJraWQiOiJNWkJXVUNvQlBZRUU1ams3bHNGMEtlWVFLUkEiLCJhbGciOiJQUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5hbHBoYWJhbmsuY29tIiwiYXVkIjoiczZCaGRSa3F0MyIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwiY2xpZW50X2lkIjoiMjU3YTdmOWUtZjQ2Ny00NzBhLWE2NTQtMmM3OGM1YjZiYzcxIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODQ0NC9yZWRpcmVjdCIsInNjb3BlIjoib3BlbmlkIGZ1bmRzY29uZmlybWF0aW9ucyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6IjI1NTM0NzI5MTEiLCJjbGFpbXMiOnsidXNlcmluZm8iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiQUktMUVEQzYxRDItMTAzNC0xMUVBLTg0RjAtN0YwMDAwMDEwMDAwIiwiZXNzZW50aWFsIjp0cnVlfX0sImlkX3Rva2VuIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6IkFJLTFFREM2MUQyLTEwMzQtMTFFQS04NEYwLTdGMDAwMDAxMDAwMCIsImVzc2VudGlhbCI6dHJ1ZX0sImFjciI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI6WyJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJ1cm46b3BlbmJhbmtpbmc6cHNkMjpjYSJdfX19fQ.OoNa_7pT76Xfasdfa8123jfsdf2Dw70qF4bfZeQxfwsdfsdfJdKcqHAAYR4a_LFK2XJo9EPCVg2kMOCMe1XBhUJpn6he8IIV6Qpx8Pti5dMDUDEpITLPWkYabldFlukoFGhSlpsOArA_Ctk0nCG2oNEEBT7PwlZwr7aeSGAdWwkJBJwBFqwLk7zdhLxrY5TaEgH6mhMFyxfGmmtanXvi2RpcWJLhsQYJAvgz3d5Xqrkauy5qOEKSJIyWClqRfMUvHBofWxinFkzhOFw9s5J7XCDSel6pk-lmIjpx4GeJHQVUXTkEYOPEfZgI2zTbFEX_bQD85j3TmKTHmd5oN0kwA
 

5. Redirect to PSU Authentication

Open the following URL in a browser to get redirected to the PSU Authentication. See the Getting Started page for information about how to obtain a test user.

https://api.mhbkemea.co.uk/mhbkemea/sb/oidc/oauth2/authorize?scope=accounts&redirect_uri=(redirect_URL)&response_type=code%20id_token&client_id=(client_id)&nonce=(nonce)&request=(JWT as created in the previous step)
6. Redirect back from PSU Authentication
When the PSU authentication was successful, the PSU will be redirected to the configured redirect URL with a set of parameters in the URL. 
Note the value of the "code" parameter, which will be required in step 8
7. Create ID Token

When the PSU has been authenticated, create an identity token with the following data in order to re-authenticate with the SPG:

Header: {"kid":"(signature_key_id)","alg":"PS256"}
Payload: {"iss":"(client_id)","sub":"(client_id)","nbf":1499183601,"exp":1599183601,"iat":1539183601,"jti":"id123456"}
Signature: (create using the according signature key)
 

For example: eyJraWQiOiJNWkJXVUNvQlBZRUU1ams3bHNGMEtlWVFLUkEiLCJhbGciOiJQUzI1NiJ9.eyJpc3MiOiIyNTdhN2Y5ZS1mNDY3LTQ3MGEtYTY1NC0yYzc4YzViNmJjNzEiLCJzdWIiOiIyNTdhN2Y5ZS1mNDY3LTQ3MGEtYTY1NC0yYzc4YzViNmJjNzEiLCJuYmYiOjE0OTkxODM2MDEsImV4cCI6MTU5OTE4MzYwMSwiaWF0IjoxNTM5MTgzNjAxLCJqdGkiOiJpZDEyMzQ1NiIsInR5cCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vcmVnaXN0ZXIifQ.eOwOlzFyxy6NbUASpbfnXxV3YyOUGYcpZdr4MEaHMs1INZa6K5jqSRYvdaX3rXcwGEyrmjEDLDWKyWoK5T5-yznf0aS-HxMTwLPnO9oLvZ6vWakUHeItDn6BjCfsZfxEuMvCEck9bjk8FN1Dzef0dFqO7f0YUD6M9WWNr2-8BlGSGTGIu7AjpuIU-svkortLMLgStOJk-1f5UxNYNfEOq7uhV8Ilf075AOS9u4TCq4WZFST_p0bNG4D2DYRJZIAxZuSvyhkhkD2hg8vqz8vxhps5nZqBPVrjBdPza7AQ1mNkC4ga2NUogbV1naLovkMX7jUczeJs0HquPg4x-nkGQw

8. Re-Authenticate with Authorisation Code

Execute the following curl command to re-authenticate and obtain a new bearer token

curl -X POST https://api.mhbkemea.co.uk:446/mhbkemea/sb/confidential/oauth2/token --cert (OB_transport_certificate).pem --key (OB_transport_key).key --insecure -H Accept:application/json -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer -d grant_type=authorization_code -d client_assertion=(identity_token as created in step 7) -d code=(code as retrieved in step 6) -d client_id=(client_id) -d client_secret=(client_secret) -d redirect_uri=(redirect_URL)

Note the value of the new bearer token in the response.

9. Invoke the APIs

Execute the following curl command using the new bearer token.

curl -X GET https://api.mhbkemea.co.uk:446/mhbkemea/sb/open-banking/v3.1/aisp/accounts --cert (OB_transport_certificate).pem --key (OB_transport_key).key --insecure -H Content-Type:application/json -H Accept:application/json -H Authorization:"Bearer (bearer_token)" -H x-fapi-financial-id:0015800001HQQt0AAH -H X-IBM-Client-Id:(client_id) -H accept:application/json