Authentication

All requests must be authenticated using OAuth. Please consult http://oauth.net/documentation/getting-started/ for an introduction to OAuth. OAuth libraries for different programming languages are listed at http://oauth.net/code/.

Long story short, you need a consumer_key and a consumer_secret. The consumer_key is a little bit like your username and is part of the request. As for the consumer_secret, well, it's a secret and must be kept to yourself.

The consumer_secret is used to generate a signature for the request. The signature is included in the request itself just before you send it. When we receive it, we generate the signature with your consumer_secret and if it matches the signature you specified, we know the request comes from you.

2-legged vs. 3-legged signatures

By default, you should be signing API calls using 2-legged OAuth. In other words, the access token and access token secret parameters are simply left empty. If every single request you will make to Context.IO comes from servers you (and only you) have full control over, this is a perfectly fine and secure way to authenticate calls and control access to users connected to your key.

However, if you're building a mobile application or a browser extension that will make direct requests to Context.IO you must enable 3-legged signatures for your API key.

A more generic way to explain this would be as follows: if your consumer secret is distributed in any way, shape or form on a server or in client code that isn't under your exclusive control, make sure your API key is configured for 3-legged signatures. This ensures that any distributed device that knows you consumer secret won't have access to users other than those added from the device itself.

Working with 3-legged signatures

With 3-legged signatures enabled, every user under your key gets a unique access_token and access_token_secret assigned to it when it is created (see the POST request on users for more info). These values will then be required to sign requests on that specific user.

OAuth Provider Scope

Google note

Connecting a Google account to Context.IO requires a couple of steps. First on the Google Developer Console create a new application if you have not already. When creating the application it is important to use the correct scope for the OAuth refresh token. To connect to the IMAP servers the scope must be full access https://mail.google.com/. See the Google documentation here. Also it is important to set the redirect URL. The redirect url you should use is https://api.context.io/connect/oauth2callback.

After you have obtained an Auth token with the proper scope go to the Context.IO console and click on "OAuth access to IMAP" under "Settings". Select " Standard Gmail / Google Apps OAuth2 (3-legged)" under “Add an OAuth Consumer”. Enter your consumer and secret key. Click on "Add". The consumer and secret key can be found at the Google Developer Console.

Microsoft note

To connect a Microsoft account to Context.IO requires a couple of steps. First, on Microsoft Live Connect create a new applicaiton if you have not already. Click on “API Settings” and under redirect URLs, add the following URL, https://{CIO OAuth Key}.api.context.io/connect/mslivecallback, then click “Save”.

Second, go to the Context.IO console, and click on “OAuth access to IMAP” under “Settings". Select “Microsoft Live Connect” under “Add an OAuth Consumer” and enter your Microsoft Live Connect consumer key and secret. Click on “add”. Your key's can be found at Microsoft Live Connect.

Important notes

  • For now, we only support HMAC-SHA1 for signatures.
  • OAuth parameters can be appended as URL parameters or sent as HTTP AUTH headers.
  • If you're having issues getting your signatures working, the API Explorer in the Developer Console shows details of parameters involved in signing the API calls.