Sign In Try it free

Creating an Integration

Prerequisites

This guide assumes you've already done the following:

Overview

An integration contains the access tokens which are issued by the 3rd-party service and allow Work-API to access those servies on behalf of a user.

Adding API credentials

In order to make requests on behalf of the developer, credentials must be entered via the Dashboard which allow Work-API to identify as the developer when making calls to the underlying APIs.

When setting up the OAuth credentials on the underlying provider, the Work API OAuth callback URI must be provided as a redirect. Failure to do so will mean users are not able to add integrations.

NOTE:
The Work API OAuth2 redirect URI is:
https://api.work-api.com/auth/callback

For information on adding API credentials to the Work API, see Create an Environment

Adding an Integration

Once a set of credentials is stored in the WorkAPI database, the user can then connect their accounts to the system.

Creating the Integration record

The first step is to create an integration via the API.

Example
token = "<user token>"
client = LivilApi::Service.new(token)

provider = 'gmail'
media_type = 'email'

integration = LivilApi::Integration.new(provider: proivder, media_type: media_type)
created_integration = client.create_integration(integration: integration)

created_integration
# => LivilApi::Integration(provider: 'gmail', media_type: 'email', ...)

Authorizing the Integration using OAuth2

The user must explicitly grant permission for WorkAPI to access their account on the underlying service.

The standard process to do this is using OAuth2.

There may be some services which don't support OAuth2 and so the process will be slightly different. That will be covered in documentation for those providers as necessary.

The first step of the authorization process is to send the user to a generated URL which allows the user to approve WorkAPI's access and then pass the access tokens back to the WorkAPI.

The user should be directed to the URI which is returned by this call. They can optionally be redirected automatically using a 302 redirect on the WorkAPI servers.

Once the process is complete, the user is then able to access their data via the WorkAPI.

NOTE:
The access and refresh tokens provided by the 3rd party service are not visible to the developer and held only on the WorkAPI servers.

Example

token = '<user token>'
client = LivilApi::Service.new(token)

integration_id = '<ID of previously created integration>' 
return_to = 'https://mydomain.com/success' # the URL to which the user should be redirected after successful authorization

result = client.auth_integration(integration_id: integration_id, return_to: return_to)

result
# => { uri: 'https://accounts.google.com/....' }

Authorizing the Integration on Android

Google does not allow authorization of integrations via WebView and so a different route must be taken

A detailed tutorial on integrating Google Sign-In for Android can be found here.

After authorizing the Android app on the device, the serverAuthCode must be passed to the following URL:

POST https://api.work-api.com/auth/authcode/<integration_id>

Authorization: Bearer <token>
Content-Type: application/x-www-form-urlencoded

code=<code>

NOTE:
A sample Android app for connecting your device with Work-API can be found on Github, here: https://github.com/Work-API/android-oauth-sample

The correct scopes must be specified for the integrations you wish to add to your application.

  • Gmail:
    • email
    • https://mail.google.com/
  • Google Calendar:
    • email
    • https://www.googleapis.com/auth/calendar
  • Google Drive:
    • email
    • https://www.googleapis.com/auth/drive

First 50,000 requests are free every month

Try it free