Completing a Connection

When a user gets redirected back to your client's redirect URI, you will be able to complete the connection by doing an authorisation grant token request.

To do this, you'll need to call our /token end point - see our authentication documentation for how to authenticate against this end point - and pass in the following body, along with any authentication fields specified in the authentication document:

Field	Type	Description
grant_type	string	Will always be `authorization_code` for this instance
code	string	The authorisation code that was sent in the redirect URL
redirect_uri	string	The redirect URI that was used for the connection
sub	string	User ID for for the connection that you are connecting for (for AIS only)

The authorization_code grant type is implemented according to the specs in RFC6749 and OIDC, with the addition that you can send the user id as a sub parameter.

🚧
sub parameter
The sub parameter helps to verify that the code that is exchanged belongs to that user authorisation process. It is recommended to pass in the sub value for AIS connections so that connections that start and end on different browser sessions can still complete.

Authorization codes last for 10 minutes, and can only be used once.

Example of an authorization_code grant request using client secret basic auth

curl -X POST 'https://identity.moneyhub.co.uk/oidc/token' \
  -H 'Authorization: Basic Base64_encode(<client_id>:<client_secret>)'\
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=example-auth-code&redirect_uri=example-redirect-uri&sub=example-user-id'

Example of an authorization_code grant request using private key jwt auth: more information on private key jwt can be found here

curl -X POST 'https://identity.moneyhub.co.uk/oidc/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=aPQQLsjGonYICd4fyc6SbaCmLPE&redirect_uri=http%3A%2F%2Flocalhost%3A3001&client_id=1e1b2556-6e29-426c-9a52-8cd5b9019c72&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkpXQnliRXcxc19KSWpLUFh2UHpSTlFmZExBa2o5MElKSjJoRmQ2b29xaE0ifQ.eyJpYXQiOjE2MjU2NjU4MjUsImV4cCI6MTYyNTY2NTg4NSwianRpIjoiNGw2b1h4b1NBOW9TaGZKWU1telFMcDN5RUVzc1k0RG04Vmk5cW5MQU9GMCIsImlzcyI6IjFlMWIyNTU2LTZlMjktNDI2Yy05YTUyLThjZDViOTAxOWM3MiIsInN1YiI6IjFlMWIyNTU2LTZlMjktNDI2Yy05YTUyLThjZDViOTAxOWM3MiIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHkubW9uZXlodWIuY28udWsvb2lkYy90b2tlbiJ9.VkdC0H3demnqTWG1eDlKD--ZuovBL8N2jpNU9xCxPbg9737RWb94pAanebcc4LTy5Ci_J8vEl81dZZkEAF_P9v2lL5QvJ4OHlupv6JEzJoLjohCgnJaYFlvRd6iXHoK-gnOpMQgu4OB7jXtXRgDHopee2O86M0q-2gW_VnrKLFpA4-_p0DolgQjKB80ojr52MRN_D-sZVPBE2qAwa8ueOknYW9eTq4E2AHULfUwSzTC7_xgOqd76DWtCpwIuWvkiVylTFQ-GZzo3sI4cisnnnaNBfkTuRROyHAAoRetZRWhya8b41MoXrGpbHKwAlW3j2jCQQewhd2nCqeQ2_KqM-A&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&sub=example-user-id'

Example of an authorization_code grant request using the moneyhub api client

// @mft/moneyhub-api-client
const paramsFromCallback = {
  code: "example-auth-code",
  state: "example-state",
}
const localParams = {
  sub: "example-user-id",
  nonce: "example-nonce",
  state: "example-state",
}
const result = await moneyhub.exchangeCodeForTokens({paramsFromCallback, localParams})

Token set returned when exchanging a valid authorization code:

{
  access_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRxVk1laV9XdUtqZW5HWlJUbnJpeUxXRnZuS2tzTjNvLWFuWXBqS0JEbVUifQ.eyJqdGkiOiJLYkFwQVo1UDk5R2RfckdTQXl6bDMiLCJzdWIiOiI2MDUzN2IwNzRjNGI2ZmRmMTIwMjQ2NTgiLCJpc3MiOiJodHRwczovL2lkZW50aXR5Lm1vbmV5aHViLmNvLnVrL29pZGMiLCJpYXQiOjE2MTYwODM3NDMsImV4cCI6MTYxNjA5MDk0Mywic2NvcGUiOiJpZDoxZmZlNzA0ZDM5NjI5YTkyOWM4ZTI5Mzg4MGZiNDQ5YSBvcGVuaWQiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsic3ViIjp7ImVzc2VudGlhbCI6dHJ1ZSwidmFsdWUiOiI2MDUzN2IwNzRjNGI2ZmRmMTIwMjQ2NTgifSwibWg6Y29uX2lkIjp7ImVzc2VudGlhbCI6dHJ1ZX0sImF1dGhfdGltZSI6eyJlc3NlbnRpYWwiOnRydWV9fSwicmVqZWN0ZWQiOltdfSwiYXVkIjoiMWUxYjI1NTYtNmUyOS00MjZjLTlhNTItOGNkNWI5MDE5YzcyIn0.eP90PFkfrh9syOpit_8SPutsjEN_KaZN23bR5VL43_tRjxKL5Rxc2M1HVMfUY2WraEEjC9fqwGpW3L3otPpzn1iZWy3SjS0iUcz1VCbucEOWvwjuAHUc0hQSqoDx97oJTnWiFZ_mGmk65xK_W4botUjaxlCu7iUUJsREB5C9vruo370Q2-m9fQZ4HthhsDxKAbjAy9v5ln6E4NUufkC7XPu3Yg1Nx8sTvI0a79XJ622t2Chy0z3QncoJIbBHawc6jbD-GfsrUMP0PEdB9RTlbSkn2mt1I8KpUomyWJ4E05ys3CuIoiWP2b6MMHRFgeAJinIN06uQZ0eQblySsC-urw',
  expires_at: 1616090946,
  id_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRxVk1laV9XdUtqZW5HWlJUbnJpeUxXRnZuS2tzTjNvLWFuWXBqS0JEbVUifQ.eyJzdWIiOiI2MDUzN2IwNzRjNGI2ZmRmMTIwMjQ2NTgiLCJtaDpjb25faWQiOiIxZmZlNzA0ZDM5NjI5YTkyOWM4ZTI5Mzg4MGZiNDQ5YTowNjczN2ZmZS1jZGZmLTQwNDctYTFkMy1iNTRlYmM4YzM2OGIiLCJhdXRoX3RpbWUiOjE2MTYwODM3MzAsIm5vbmNlIjoiYmFyIiwiYXRfaGFzaCI6IjI1ODg2UXNaTDZIY2VfZ3Y5YU9XUWciLCJzaWQiOiI3N2I1OGZjMS0wZTMwLTQxMjMtYWVmZi04YzcwZTczMDJmMzIiLCJhdWQiOiIxZTFiMjU1Ni02ZTI5LTQyNmMtOWE1Mi04Y2Q1YjkwMTljNzIiLCJleHAiOjE2MTYwODczNDYsImlhdCI6MTYxNjA4Mzc0NiwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS5tb25leWh1Yi5jby51ay9vaWRjIn0.Upy5ThfFepYYldLL_RVBFMKjBoIWnUfZM6INF2v7572gH3B4fWBuTfQGvWHuf1NJ9szmiNN1_g09b_XI9lSCPzIXnrS-jeEgiMuCbiZISxxbRgS0Swg2XFay2LlgcWTijRBcq2r9o0KpacoXtxU2OSjJY6Q2ahF8H6HRwQHL0-zZAIj_XL8iMvgmXDwIjifSXj9wCxljS1R_3rRr1IYLIxvoSKK9NhJet4PHv-ICbApR5tFjN7ulVjR6V1rEkQDAvj9WmZFL3L2BMKEV9ZvhU773bHATNJ-ehebWr5qXzDxRsGgB4MeWc-Fy0cz4DqiiHwhNTr3sBdD1Pge0gIDv-w',
  scope: 'id:1ffe704d39629a929c8e293880fb449a openid',
  token_type: 'Bearer'
}

The id token can be decoded to get more information about the user and the connection or payment performed:

{
  sub: '60537b074c4b6fdf12024658', // userId
  'mh:con_id': '1ffe704d39629a929c8e293880fb449a:06737ffe-cdff-4047-a1d3-b54ebc8c368b',
  auth_time: 1616083730,
  nonce: 'bar',
  at_hash: '25886QsZL6Hce_gv9aOWQg',
  sid: '77b58fc1-0e30-4123-aeff-8c70e7302f32',
  aud: '1e1b2556-6e29-426c-9a52-8cd5b9019c72',
  exp: 1616087346,
  iat: 1616083746,
  iss: 'https://identity.moneyhub.co.uk/oidc'
}

🚧sub parameter

🚧
`sub` parameter