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
- miiCard 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
Your application can request stronger assurance of a member’s identity by requiring they submit to a two-factor authentication 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. Charges may apply to enable this service - miiCard will be able to discuss this when you request your consumer key and secret.
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
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
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.
In some situations it can be useful to skip the data sharing page during the OAuth workflow, for example when you are using miiCard as a sign-in mechanism. miiCard can configure you account to skip this page on request - please use our support form.
- The first time a miiCard member goes through the process, they will be shown the data sharing page and will need to confirm what data to share
- On every subsequent time the member goes through the process they won't be shown that screen, and shall simply be redirected straight to your application UNLESS:
- The member revokes access to your application
- The member-specified automatic revocation date has passed
- You make any change to your product configuration, including:
- Its name
- The set of details you wish miiCard members to share
If miiCard enable this functionality but you need to force specific requests to cause the data sharing page to appear, you can use the OAuth redirect parameters described on the Authorising With OAuth page.