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_grant 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

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.

The sub parameter helps to verify that the code that is exchanged belongs to that user authorisation process.

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'
}