Claims

When creating an authorisation URL, you specify a set of claims that gives us extra information for how the connection will be made. Our discovery document details the claims that we support, they currently include:

• User ID the connection will belong to
• Whether you want the connection ID returned in the resulting ID Token
• Whether you want the connection to be made asynchronously (these connections won't wait for the first batch of account and transaction data to return before the connection is complete)
• Request information on whether a certain counterparty is present in the resulting transactions.
• Category type to be applied to transactions received through the connection
• Information about a payment to initiate.

Generating a Claims Object

You can find more information in the OIDC specification on claims requests. But below is an introduction on how claims are used.

A claim request is simply a JSON object that describes what information you wish to request. All our claims we support currently belong for to the id_token so the object will look like:

{
  "id_token": {
    "sub": {
      "essential": true // recommended so that you get the user ID for the connection
    },
 	  // Moneyhub claims
  }
}

📘

Providing a User ID for a Connection

If you want to make a connection for a given user, you will specify the user ID within the sub value of the claim.

Providing the Claims Object

If you are not using a request object in your authorisation URL, you need to ensure that the claims object is URL encoded. So for example, the following URL claim: %7B%22id_token%22:%7B%22sub%22:%7B%22essential%22:true%7D,%22mh:con_id%22:%7B%22essential%22:true%7D,%22mh:sync%22:%7B%22essential%22:true,%22value%22:%7B%22enableAsync%22:true%7D%7D%7D%7D would be equivalent to:

{
  "id_token":{
    "sub":{
      "essential":true
    },
    "mh:con_id":{
      "essential":true
    },
    "mh:sync":{
      "essential":true,
      "value":{
        "enableAsync":true
      }
    }
  }
}

These claims mean:

• Return the user ID for the connection
• Return the connection ID for the connection
• Make the connection asynchronously
  • Also return the ID of the sync for the new connection

If you are using a request object, simply include the claims object within the request object to be encoded.

Completing the Connection

On completion of a connection, you will get an ID Token which will include the information requested in the claims, for example for a claim request that was given above, you'll get:

{
    "iss": "https://identity.moneyhub.com",
    "sub": "24400320",
    "aud": "s6BhdRkqt3",
    "nonce": "n-0S6_WzA2Mj",
    "exp": 1311281970,
    "iat": 1311280970,
    "mh:con_id": "the-connection-id",
    "mh:sync": "sync-id"
}