SHIFT Developers

Getting Started with OAuth 2.0 Integration

The OAuth 2.0 spec provides a secure model for third-party authentication and resource sharing between web services and applications. The SHIFT OAuth implementation allows users to install your application on the SHIFT platform, enabling effective collaboration and communication around objects within your application.

Once SHIFT OAuth is integrated into your application, your application will be able to:

Be installed on a SHIFT team and receive all relevant data.
Allow users to automatically authenticate through OAuth, creating a session on your application domain.
Receive notifications on team events, including new users, changed team information, and more.
Create Application Objects as references to your data on the SHIFT platform.
Post messages to the SHIFT team, including messages referencing objects within your application.
This tutorial will cover setting up a sample application and performing all of the above actions through the SHIFT API.

Step 1: Obtaining your Client ID and Client Secret

To start using OAuth integration, you will need to create an Application on the Shift Developer Center. Once you create an application, record it's Client ID and Client Secret, as these values will need to be used in your application code.

Sample Client ID: a2541eea-f040-45a6-bca5-b7ad26d1b279

Sample Client Secret: 1f4336dd-5684-4407-82b1-d91487ea64f7

Step 2: Handling Application Install

In the SHIFT Developer Portal, set a pre-install callback on your application. This callback must return a HTTP status code of 200 for the application to be able to be installed on a team. If the install callback returns a non-200 status code, the application installation will fail.

Set up the non-restricted route (i.e. not behind any type of authentication) on your application, then attempt to install the application on a team. Ensure that sufficient logging is setup on the install route on your application so that you will be able to debug any issues that arise that result in the application install failing due to this route returning a non-200 response code.

A client_secret field will be included in the install callback data. Make sure to validate this against the client secret that was provided when you created your application on SHIFT.com, they should match exactly.

Sample POST body on the application install route:

{
  "installer": {
    "superuser": false,
    "last_name": "Testerson",
    "updated_at": 1351042439.021,
    "images": [],
    "id": "1a84761d-757c-4596-93e8-81d36bf6702f",
    "developer": false,
    "first_name": "Testy",
    "title": "",
    "primary_phone_number": {},
    "location": "",
    "primary_email": {
      "user_id": "1a84761d-757c-4596-93e8-81d36bf6702f",
      "company": null,
      "verified": false,
      "id": "ee1e2baa-7059-43ee-9589-e3bb4ccab7f5",
      "address": "test553763357265881011401179398164@grapheffect.com"
    },
    "facebook_id": null,
    "alternate_emails": [],
    "prefs": {
      "email_on_team_invite": true,
      "email_on_team_removed": true,
      "email_on_reply_to_your_direct_message": true,
      "email_on_at_mention": true,
      "email_on_shift_update": true,
      "email_on_direct_message": true,
      "email_on_sidebar_message": true,
      "email_on_team_role_changed": true,
      "email_on_team_message": true,
      "email_on_reply_to_message_you_replied_to": true
    },
    "username": "test_954552192437866",
    "online": false,
    "online_info": null,
    "pending_domains": [],
    "active": true,
    "password": null,
    "alternate_phone_numbers": [],
    "created_at": 1351042439.017,
    "companies": []
  },
  "team": {
    "num_members": 1,
    "name": "Team207133209866746584721729856905",
    "color": "blue",
    "created_at": 1351042439.023,
    "updated_at": 1351042439.102,
    "unread_count": 0,
    "active": true,
    "id": "886cd5ba-374b-4989-8810-332827735643",
    "icon": "turtle"
  },
  "type": "team",
  "users": [
    {
      "superuser": false,
      "last_name": "Testerson",
      "updated_at": 1351042439.021,
      "images": [],
      "id": "1a84761d-757c-4596-93e8-81d36bf6702f",
      "developer": false,
      "first_name": "Testy",
      "title": "",
      "primary_phone_number": {},
      "location": "",
      "primary_email": {
        "user_id": "1a84761d-757c-4596-93e8-81d36bf6702f",
        "company": null,
        "verified": false,
        "id": "ee1e2baa-7059-43ee-9589-e3bb4ccab7f5",
        "address": "test553763357265881011401179398164@grapheffect.com"
      },
      "facebook_id": null,
      "alternate_emails": [],
      "prefs": {
        "email_on_team_invite": true,
        "email_on_team_removed": true,
        "email_on_reply_to_your_direct_message": true,
        "email_on_at_mention": true,
        "email_on_shift_update": true,
        "email_on_direct_message": true,
        "email_on_sidebar_message": true,
        "email_on_team_role_changed": true,
        "email_on_team_message": true,
        "email_on_reply_to_message_you_replied_to": true
      },
      "username": "test_954552192437866",
      "online": false,
      "online_info": null,
      "pending_domains": [],
      "active": true,
      "password": null,
      "alternate_phone_numbers": [],
      "created_at": 1351042439.017,
      "companies": []
    }
  ],
  "client_secret": "d683b7e8-356f-4697-8cac-f01e134cd7ce"
}

Step 3: Setup your OAuth Endpoints

You will need an OAuth 2.0 redirect endpoint (route) set up for your application. This route must be available through HTTPS. SHIFT will make a GET call which will include an authorization code and shift_team_id parameter. This call will be made every time a user attempts to use your application.

Make sure to add this endpoint as the redirect_uri setting to the OAuth section of your app settings in the SHIFT Developer Portal.

For the GraphEffect application, we setup this route at https://grapheffect.com/oauth/redirect. SHIFT calls this route with the following URL: https://grapheffect.com/oauth/redirect?code=yjplBJeKZZHwUxZztQ7iuMehQ0BahEw9VBb7twaX&shift_team_id=ea27198d-3b35-4d60-a049-e7cca7578c89. As you can see, an OAuth authorization code and the SHIFT team id are passed through to your application. This route must return a HTTP 302 Redirect and redirect to your application after setting up the user session. The overall redirect flow is as follows:

GET /oauth/redirect?code=auth-code&shift_team_id=shift-team-id
Make a POST to https://go.bn.co/v1/oauth2/token with the following POST params:
- code=auth-code
- client_id=client-id
- client_secret=client-secret
- grant_type='authorization_code'
- redirect_uri=redirect-uri

If everything goes well, you will get a response like::

{
  "access_token": "YfADGVXwFHQYevNojcWBGDnYqZo98mvCdVwSdfnw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "VDit31GM7edYBbhvFvb0a2Sf41FESq1GwZC7uPKD"
}

Use the access token to make a request to obtain user information, which you will then be able to connect to your session and login the SHIFT user into your application. GET https://go.bn.co/v1/users/me

Headers:

Authorization: Bearer <access-token-here> You will receive the user object as specified in the :doc:User API </modules/users> section in this documentation.

Use the user information to check for an existing user in your application, by SHIFT id, primary_email, etc, and create a new user if needed.
Create a session on your application for the current SHIFT user.
Finally, redirect to your main application interface. The user is now authenticated through SHIFT. Be sure to direct the user to the appropriate space within your system that represents the SHIFT team that the user is currently accessing your application in.

Step 4: Authenticate a User through OAuth

Try to click on your application on a SHIFT team and observe any errors in the previously created flow.

If all is well, you should now be using your application within the SHIFT platform.

Step 5: Create an Application Object Referencing an object in your Application

For SHIFT's own application GraphEffect, we have Facebook Pages in the Story Manager section of our application.

When a page is updated or created in GraphEffect, we maintain a shift_id on the page model with the ID of the corresponding Application Object on SHIFT. To create the object, we make a POST call as laid out in the Application API with the following data:

POST /v1/applications/your-client-id/objects?client_id=your-client-id&client_secret=your-client-secret


{
    "url": "/#/story-manager/pages/123456789",
    "type": "page",
    "team": "a2541eea-f040-45a6-bca5-b7ad26d1b279",
    "name": "GraphTest"
}

The response data will include an id parameter containing the SHIFT id of the newly created Application Object, which should be persisted and associated with your application's internal object for future reference.

Step 6: Post a message about the Application Object to the Team

For the final step in this tutorial, post a message from your application using the SHIFT Message API as an OAuth-authenticated SHIFT user to the relevant SHIFT team.

In GraphEffect, we post a message to SHIFT whenever a user posts on a Facebook Page using our software. The POST call looks like this:

POST /v1/messages
HEADERS:
Authorization: Bearer <user-access-token>
Content-type: application/json

{
  "addressed_users": [],
  "text": "Posted to page {0}",
  "addressed_teams": [
    "a2541eea-f040-45a6-bca5-b7ad26d1b279"
  ],
  "mentions": [{"type": "appobject", "id": "d346b0ee-de50-405d-bcbd-b2828587d256", "name": "GraphTest"}]
}

Congratulations! You should receive a message in your test team.

Guides & Tutorials