How to add users to Context.IO

Authentication options for your end-users

In order to connect a mailbox to Context.IO, a user will need to authenticate an account. Context.IO supports connections made in any of the following two ways:

  • 1) Oauth
  • 2) Password

Connecting via oauth is the best and most reliable way. In fact, some providers, such as Microsoft, require connections be made via oauth. We currently support oauth connections for Google and Microsoft accounts.

For non oauth accounts, we can connect via IMAP over a secure connection using SSL. You can learn more about both options below.

Connecting via oauth

Google and Microsoft require users authenticate via oauth. Context.IO supports oauth for Google and Microsoft in two ways: by handling your own oauth, or by using our connect tokens feature.

Handling your own oauth: A developer can authenticate via Oauth 2.0 by passing Context.IO their provider consumer key (an API key obtained from Google / Microsoft), as well as a provider refresh token, which is also obtained from the provider. If this option is chosen, the developer must handle their own token refresh. You can add the user with this endpoint.

Using our connect tokens feature: The Context.IO connect tokens feature is an abstraction on top of oauth. In other words, it is a feature Context.IO developed to facilitate the oauth process on behalf of a developer. If a developer chooses this option, all they have to do is create a connect token in order to “kick off” the oauth process, and we handle the rest (i.e. redirecting the user to authenticate to the correct provider, requesting the right scope). Another benefit to using our connect tokens feature is that we handle token refresh with the providers, so developers don’t have to worry about refreshing oauth tokens. You can add a user with connect tokens using this endpoint

Specific types of oauth accounts supported:

  • 1) Google: Gmail and Google Apps
  • 2) Microsoft: Outlook.com, Hotmail, MSN

Please note: Outlook over Office365 is not supported via oauth, as that is an Exchange server, and we do not support native Exchange. To connect to an Outlook Office365 account, you must connect via IMAP (and the end-user must have IMAP enabled).

Non-oauth access

For providers that do not support oauth (i.e. not Gmail / Microsoft), we connect securely via IMAP using SSL. Usernames and passwords are stored securely and are encrypted. A developer can use either of the following options to authenticate non-oauth accounts:

Passing us credentials at account creation: If this method is chosen, the developer would need to know details such as IMAP server, port, SSL connection, and get the username and password from the end-user, and send this information via a POST request to this endpoint.

Using our connect tokens feature: Context.IO connect tokens also facilitates the creation of non-oauth accounts by “auto-discovering” IMAP connection settings. If a developer chooses this option, Context.IO will attempt to populate the data needed to form a secure IMAP connection based on our auto discovery data, and all an end-user would have to do is provide their username and password. We also provide a GUI to gather credentials from the end-user, which developers can add their own branding to.

Choosing the right authentication method

For providers that support oauth (Google or Microsoft):

If you all wish to do is simply connect to an account, our connect tokens feature is the best and fastest way to accomplish this. If you choose this option, we strongly urge you to add your own provider keys so that when a user checks to see which apps have access to their account, they will see your app and not Context.IO (in fact, Microsoft requires this).

If you need to do more complicated things with oauth, such as use a refresh token to authenticate on more than one application (i.e. more than just Context.IO), you should handle your own oauth.

For providers that do not support oauth:

Once again, our connect tokens feature is a great way to handle connections for providers that do not support oauth. This is because the Connect Tokens feature can auto-discover the IMAP settings necessary to make a connection, and all the user would need to provide is their username and password.

If you do not need to auto-discover IMAP settings (i.e. your application will only connect to the same IMAP providers, and you already know these settings), you could very well simply pass the IMAP server, port, SSL settings, username and password manually to the API via POST request to the users endpoint.

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.