connect_tokens

While your code can create a new user and connect an email account to it with API calls, you still need to implement the UI for this in your app, including the process to obtain OAuth2 tokens from Gmail, Google Apps and Outlook.com users.

To make this easier, Context.IO provides the connect_tokens resource. When users are ready to connect their email account to it, your app simply obtains a new connect_token and redirect users to the corresponding URL included in the POST response.

Users will then be presented with a standard form to either complete their connection settings or grant your application access through OAuth2. Once the process is complete, control is passed back to your app. The sequence is illustrated below.

Connect Tokens Sequence

We recommend that you obtain your own oauth2 client ID from Google and Microsoft so that your users can correctly authorize your application.

  • For Google, please register https://api.context.io/connect/oauth2callback as a valid redirect URI when obtaining your client ID at https://code.google.com/apis/console.
  • For Outlook.com, please register https://<your_oauth_key>.api.context.io/connect/mslivecallback as a valid redirect URI when obtaining your client ID at https://user.live.com/developers/applications. Note that you must replace <your_oauth_key> with your Context.IO oauth key.
    • Supported methods

      List methods:GETPOST

      Instance methods:GETDELETE

      connect_tokens list

      GET: List of connect tokens created with your API key

      GET https://api.context.io/lite/connect_tokenstest it

      Response body

      [
        {
          "token": stringID of the connect token,
          "email": stringemail address specified on token creation,
          "created": numberUnix timestamp of the connect token was created,
          "used": numberUnix timestampof when this token was used. 0 means no user has been created with this token yet,
          "expires": mixedUnix timestamp of when this token will expire and be purged. Once the token is used, this property will be set to false,
          "callback_url": stringURL we'll redirect the browser to after the user is created,
          "first_name": stringFirst name specified on token creation. Defaults to first_name of the user,
          "last_name": stringLast name specified on token creation. Defaults to the last_name of the user,
          "user": {
            If the connect token hasn't been used yet, this object will be empty
            "id": stringID of the user created with this token,
            "created": numberUnix timestamp of user creation time,
            "email_addresses":arrayArray of email addresses for this user. This only lists the actual addresses as strings.,
            "first_name": stringFirst name of user,
            "last_name": stringLast name of user,
            "email_accounts": arrayList of email accounts this user gets data from. See email_accounts
          },
          "account_lite": booleantrue if the account is a Lite account,
          "resource_url": stringThe URL of the connect token,
          "browser_redirect_url": stringRedirect the user's browser to this URL to have them connect their mailbox through this token,
          "serverLabel": stringThe label for the created account,
        },
        ...
      ]
      

      Making this request with a 3-legged key

      For keys configured for 3-legged signatures, all properties except the following will be set to a null value: token, created, used.

      If your key is configured for 3-legged signatures, the response from this call is restricted to avoid leaking sensitive information about individual users. To obtain this information, you have to make a GET request on the connect_token and sign it with the access_token and access_token_secret of that specific connect_token.

      POST: Obtain a new connect_token

      POST https://api.context.io/lite/connect_tokenstest it

      Parameters

      nametypedescription
      required:
      callback_urlstring
      (url)
      When the user's mailbox is connected to your API key, the browser will call this url (GET). This call will have a parameter called contextio_token indicating the connect_token related to this callback. You can then do a get on this connect_token to obtain details about the user and email account created through that token and save that user id in your own user data.
      optional:
      emailstringThe email address of the user to be added. If specified, the first step of the connect UI where users are prompted for their email address, first name and last name is skipped.
      first_namestringFirst name of the user.
      last_namestringLast name of the user.
      status_callback_urlstring
      (url)
      If specified, we'll make a POST request to this URL if the connection status of the email_account changes.

      Response body

      {
        "success": string true if connect_token was successfully created, false otherwise,
        "token": stringId of the token,
        "resource_url": stringURL to of the token,
        "browser_redirect_url": stringRedirect the user's browser to this URL to have them connect their mailbox through this token
        If your key uses 3-legged signatures, the following 2 properties are added
        "access_token": stringOAuth access token to sign all future requests on this newly created connect_token,
        "access_token_secret": stringOAuth access token secret to sign all future requests on this newly created connect_token
      }
      
      • Unused connect_tokens are purged after 24 hours, see more details below.
      • Authentication with certain third parties (e.g. Google, Microsoft) have additional requirements, please see OAuth provider scope

      The browser_redirect_url property returned when you create a new connect_token is intended to be used by your end user to connect their email account to your application. Therefore, it is a public URL that requires no session or further authentication to be served. That URL is valid for a period of up to 24 hours from the creation of the connect_token (see the expires property of a connect_token).

      If, for some reason, a user tries to use it beyond that expiration period, you'll simply need to request a new connect_token for the same email address.

      connect_token instance

      GET: Information about a given connect token

      GET https://api.context.io/lite/connect_tokens/tokentest it
      tokenThe unique random token used for the graphical user creation process

      Making this request with a 3-legged key

      If your key is configured for 3-legged signatures, each connect_token gets a unique pair of OAuth access_token and access_token_secret assigned to it (see see POST method above). Since this GET request returns sensitive information about the user created with the connect_token, you'll need to use its access_token and access_token_secret pair to sign the request.

      Response body

      {
        "token": stringID of the connect token,
        "email": stringemail address specified on token creation,
        "created": numberUnix timestamp of the connect token was created,
        "used": numberUnix timestamp of when this token was used. 0 means no user has been created with this token yet,
        "expires": mixedUnix timestamp of when this token will expire and be purged. Once the token is used, this property will be set to false,
        "callback_url": stringURL we'll redirect the browser to after the user is created,
        "first_name": stringFirst name specified on token creation. Defaults to first_name of the user,
        "last_name": stringLast name specified on token creation. Defaults to the last_name of the user,
        "user": {
          If the connect token hasn't been used yet, this object will be empty
          "id": stringID of the user created with this token,
          "created": numberUnix timestamp of user creation time,
          "email_addresses":arrayArray of email addresses for this user. This only lists the actual addresses as strings.,
          "first_name": stringFirst name of user,
          "last_name": stringLast name of user,
          "email_accounts": arrayList of email accounts this user gets data from. See email_accounts
          If your key uses 3-legged signatures, the following 2 properties are added
          "access_token": stringOAuth access token to sign all future requests on this user,
          "access_token_secret": stringOAuth access token secret to sign all future requests on this user
        },
        "account_lite": booleantrue if the account is a Lite account,
        "resource_url": stringThe URL of the connect token
        "browser_redirect_url": stringRedirect the user's browser to this URL to have them connect their mailbox through this token,
        If the connect token hasn't been used yet, key will not be present
        "serverLabel": stringThe label for the created account,
      }
      

      DELETE: Remove a given connect token

      DELETE https://api.context.io/lite/connect_tokens/tokentest it
      tokenThe unique random token used for the graphical user creation process

      Response body

      {
        "success": booleanWhether deletion succeeded
      }