Authorising with OAuth 1.0a

miiCard provides some simple API endpoints that allow third-parties to consume a subset of a miiCard member's identity information. API access requires OAuth-signed requests. Some assumptions are made about the consumers of the API:

You wish to consume miiCard verified identity information for use in your own web application
You are familiar with authorisation using OAuth 1.0a
You are familiar with making OAuth 1.0a signed requests to web services

You should set up a developer account with miiCard to obtain a consumer key and consumer secret – see the Getting Started section for details on how to do this.

The following table indicates the OAuth configuration that should be adopted by your application:

Request token URL	https://sts.miicard.com/auth/OAuth.ashx
Authorise token URL	https://sts.miicard.com/auth/OAuth.ashx
Access token URL	https://sts.miicard.com/auth/OAuth.ashx
Consumer key	Obtained by request - see the Getting Started page
Consumer secret	Obtained by request - see the Getting Started page

miiCard uses the HMAC-SHA1 signing method for OAuth 1.0a messages.

miiCard strongly recommends the use of an OAuth library for the preparation of OAuth messages and the execution of the OAuth exchange. A list of libraries for a variety of different languages is available at the OAuth.net site.

Error conditions

miiCard API methods that require authorisation will accept calls only if they contain an HTTP Authorization header with valid OAuth information. You will be unable to access these protected methods if:

You attempt to make a call to one without an HTTP Authorization header in the request.
The HTTP Authorization header has been generated using an invalid client key, client secret, access token or access secret (or is otherwise malformed).

In addition, the relying party will be unable to obtain OAuth access tokens in any situation where the miiCard member:

Elects to revoke the access token that was given to your application during authentication.
Elected to set a time limit on your access to their identity information, and that time limit has expired.
No longer has a valid miiCard subscription.

Additional parameters

You can specify some additional parameters in the redirect phase of the OAuth exchange. Most OAuth libraries support adding parameters to the query string of the redirect to the authorisation endpoint.

force_claims	If set to 'true', the miiCard member will be forced to re-confirm the information that they have shared with your application. This is of use only when miiCard has configured your product to skip the claims selector if a user already has a relationship with you. More information on this option can be found on the Authorisation Workflow page.
referrer	Specifies a referral code that should be sent with the request, allowing the user to start the sign-up process during the workflow and still have your product credited for the referral.