The miiCard API is consumed on behalf of a miiCard member, and exposes only that information which the member has consented to share with your application.
The first time your application requires access to a miiCard user’s identity details they will be guided through the authorisation wizard – a multi-step process that:
- Authenticates the miiCard member
- Optionally performing a two-factor authentication if your application requires it
- Presents the member with the set of personal details that your application is requesting, and allows them to opt in to sharing each data item
- You can configure your product to skip this step after the first authorisation for a miiCard member
- Redirects the member back to your application with authorisation tokens that represent the set of data they have elected to share, if any
Authenticating the miiCard member
The miiCard member is first asked to login with their username and password. This will always take place, even if the member has an active session on miicard.com. If they do not have an account, they can create one as part of this process.
Optional two-factor authentication
Performing two-step verification
Your application can request stronger assurance of a member’s identity by requiring they submit to a two-step verifcation process. In this situation, once the member has supplied their username and password a one-time code will be sent to their mobile phone which they then have to type into the wizard.
The member is unable to proceed with the authorisation process if they fail to perform the two-factor authentication procedure. Note that miiCard members will be familiar with this process already, as it is a requirement when they make changes to their miiCard profile.
Optional updating primary validation details
If the miiCard member's identity cannot be assured, for example because they have not associated their miiCard profile with financial account information that can verify their identity, then they will be prompted to correct the issue.
miiCard will not allow a member to share information with a third-party website until they have performed a financial validation, or if their existing financial validation has somehow lapsed – for example, because their name does not match that on the financial account.
Opt into data sharing
Choosing what information to share with your application
Your consumer key will be associated with a set of claims that you wish miiCard to make about a member's identity – these are the data-points about the member that you wish to have shared with your application.
You can mark any claim as mandatory. The member’s full name is always a mandatory claim. If an item is marked as mandatory, it is selected by default and cannot be unselected – the member can simply decline to share any information with your application if they do not want to share mandatory fields.
All non-mandatory fields are opt-in – the member must actively select each data item to be shared.
When more than one piece of data is associated with a particular field, the member will be asked to select one of them. For example, if they have verified ownership of multiple email addresses and your application has marked an email address as an optional attribute to be shared then a drop-down box shall appear.
The member can also optionally time-limit your application’s access to their personal data. After the user-specified time limit has elapsed your access to their information shall be revoked and can only be re-activated by making the member perform another authorisation process.
Member control of authorised applications
miiCard members are in total control of the data they share
Once an application has been authorised its name appears on the member's miiCard.com profile settings page along with the set of details that they elected to share.
At any time the member can revoke access to your application through this interface, though they cannot at present change the set of details that they have elected to share. The API returns status and error codes that allow your application to detect this condition.
While having the claims picker page appear at the end of the authorisation workflow makes sense for sign-up and first-time-sign-in scenarios, it can be inconvenient when offering miiCard as a login option as members must go through an additional step each time they wish to sign into your application.
To ease this, you can opt your application in to allow the claims picker step to be skipped so long as a valid relationship exists between the member and your application.
A valid relationship is one where all of the following statements are true:
- The miiCard member has previously signed into your site using their miiCard
- The member hasn't revoked access to your application since they last signed in
- The member didn't set an automatic revocation date for your access to their data, or they did but it hasn't passed yet
- Your application's configuration has not been changed in any way since the last time the member agreed to data sharing, including:
- Its branding
- The set of details you configured that miiCard members should be asked to share
- The 'allow skip claims picker' setting itself
- All of the data agreed to be shared by the member still exists in a verified form in their profile
Your application can force the claims picker to be shown for a given authorisation workflow instance by including a special parameter in the redirect stage, described on the Additional Parameters page.