Setting up OAuth

You'll need to set up OAuth if you're building an integration with Intercom that accesses other peoples' Intercom data. This can be done in a few simple steps:

After you complete these steps, you'll be able to use your access token to execute the actions authorized by an Intercom customer.

Accessing your own data only

If you just want to access your own Intercom data, you can use Access Tokens.

If you're unsure what you need, click here to get more context on the two options.


Provide the initial information

Each development workspace automatically gives you the option to use OAuth. To start, all you have to do is tick the Use OAuth option on your Authentication page in the Developer Hub.

You'll now have two sections to fill out:

Redirect URLs

This is the URL which we POST to when your user has authorized your app to access their information. In other words, it's the URL that Intercom will use to send the authorization code for your user.

Redirect URLs must use HTTPS

The redirect will need to communicate over a TLS/SSL connection, so the URL will need to be over HTTPS.

Multiple Redirect URLs

You can provide multiple URLs by selecting the Add redirect URL option after specifying your initial one. The first will always be the default.

After approval, you can choose which URL to use when you're initiating the OAuth flow via the redirect_uri parameter. This means you can include testing as well as production URLs here.

Permissions

Permissions let you specify exactly how your application needs to access an Intercom user’s account.

You should only specify the scopes you definitely need for your use case. It's best practice as these will go up for review when you submit your app for review.

The following permissions can be selected via checkboxes on your Authorization page:

People & conversation data

Standard scopes
Description

Read and list users and companies

List and view all segments, users and companies

Read and write users

List all users and execute bulk actions

Write users and companies

Create and update users and companies

Read one user and one company

List and view a single user and company

Read tags

List all tags

Write tags

Create, update, use and delete tags

Read conversations

View conversations

Write conversations

Reply to, mark as read and close conversations

Write events

Ability to submit events (i.e. user activity)

Read events

List all events belonging to a user

Read counts

Count users and companies with specified criteria

Workspace data

Extended scopes
Description

Read admins

List and view all admins

Read one admin

View a single admin

Update admins

Update away mode for admins

Gather Messenger App data

Gather data for Messenger Apps

Manage webhooks

Create and update webhooks

Get the authorization code

You'll first need your client_id and client_secret. These can be found on the Basic Information page for your app in the Developer Hub.

To get the Authorization Code, you simply need to send a GET request to the following address:

https://app.intercom.io/oauth?client_id=___&state=___

Your user will follow this link to the Intercom site and will be presented with the permissions that your app is requesting. Once the user approves this request, they are redirected back via the Redirect URLs which you provided earlier.

Intercom provides some sample code that you can use to allow the user to authorize MyApp’s request via a "Connect with Intercom" button.

Firstly, you will need to generate a Self Signed Certificate and a Private Key if you don't have SSL setup on your site. You can do so like so:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout pkey.pem -out cert.crt

Now you can use this very simple Sinatra setup with one of your publicly available endpoints to test the OAuth flow:

<a href="https://app.intercom.io/oauth?client_id=<XXXXXXXXXXXX>&state=example"><img src="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png" srcset="https://static.intercomassets.com/assets/oauth/primary-7edb2ebce84c088063f4b86049747c3a.png 1x, https://static.intercomassets.com/assets/oauth/primary@2x-0d69ca2141dfdfa0535634610be80994.png 2x, https://static.intercomassets.com/assets/oauth/primary@3x-788ed3c44d63a6aec3927285e920f542.png 3x"/></a>
#!/usr/bin/env ruby
#
# This code snippet shows how to enable SSL in Sinatra+Thin.
#

require 'sinatra'
require 'thin'
require 'json'
require 'slim'


class MyThinBackend < ::Thin::Backends::TcpServer
  def initialize(host, port, options)
    super(host, port)
    @ssl = true
    @ssl_options = options
  end
end

configure do
  set :environment, :production
  set :bind, '0.0.0.0'
  #:set :port, 443
  set :server, "thin"
  class << settings
    def server_settings
      {
          :backend          => MyThinBackend,
          :private_key_file => File.dirname(__FILE__) + "/pkey.pem",
          :cert_chain_file  => File.dirname(__FILE__) + "/cert.crt",
          :verify_peer      => false
      }
    end
  end
end

get '/' do
  File.read('intercom.html')
end

get '/home' do
  "Welcome Back"
end

get '/callback' do
  code = params[:code]
  state = params[:state]
  puts "CODE: #{code}"
  puts "STATE:#{state}"
  redirect '/home'
end

The full code example can be found here. You can copy the Intercom JS to a file, and reference it in a page where a user can click through to provide authorization. Then you will need to have a route for the Redirect URL you provided.

When you run your server and click through to authorize the user, you should see something similar outputted on the terminal:

> ruby ssl_server.rb
== Sinatra (v1.4.7) has taken the stage on 4567 for production with backup from Thin
Thin web server (v1.6.4 codename Gob Bluth)
Maximum connections set to 1024
Listening on 0.0.0.0:4567, CTRL+C to stop
[05/May/2016:10:15:44 +0000] "GET / HTTP/1.1" 200 512 0.0036
CODE: XXXXXXXXXXXXXXXXXXXXXXXXX
STATE:example
89.101.228.226 - - [05/May/2016:10:15:49 +0000] "GET /callback?code=XXXXXXXXXXXXXXXXXX&state=example HTTP/1.1" 302 - 0.0008
[05/May/2016:10:15:49 +0000] "GET /home HTTP/1.1" 200 12 0.0005 

Trade your authorization code for an access token

We can now exchange the code for the Access Token with a POST request to the Intercom Eagle endpoint.

For the simplified purposes of understanding the flow, add the following code to you callback route:

  #We can do a Post now to get the access token
  uri = URI.parse("https://api.intercom.io/auth/eagle/token")
  response = Net::HTTP.post_form(uri, {"code" => params[:code],
                                       "client_id" => "XXXXXXXXXXXX",
                                       "client_secret" => "YYYYYYYYYYYYY"})

  #Break Up the response and print out the Access Token
  rsp = JSON.parse(response.body)
  puts "ACCESS TOKEN: #{rsp["token"]}"
#!/usr/bin/env ruby
#
# This code snippet shows how to enable SSL in Sinatra+Thin.
#

require 'sinatra'
require 'thin'
require 'json'
require 'slim'
require 'json'
require "net/http"
require "uri"

class MyThinBackend < ::Thin::Backends::TcpServer
  def initialize(host, port, options)
    super(host, port)
    @ssl = true
    @ssl_options = options
  end
end

configure do
  set :environment, :production
  set :bind, '0.0.0.0'
  #:set :port, 443
  set :server, "thin"
  class << settings
    def server_settings
      {
          :backend          => MyThinBackend,
          :private_key_file => File.dirname(__FILE__) + "/pkey.pem",
          :cert_chain_file  => File.dirname(__FILE__) + "/cert.crt",
          :verify_peer      => false
      }
    end
  end
end

get '/' do
  File.read('intercom.html')
end

get '/home' do
  "Welcome Back"
end

get '/callback' do
  #Get the Code passed back to our redirect callback
  @code = params[:code]
  @state = params[:state]
  puts "CODE: #{@code}"
  puts "STATE:#{@state}"

  #We can do a Post now to get the access token
  uri = URI.parse("https://api.intercom.io/auth/eagle/token")
  response = Net::HTTP.post_form(uri, {"code" => params[:code],
                                       "client_id" => "XXXXXXXXXXXXX",
                                       "client_secret" => "YYYYYYYYYYYY"})

  #Break Up the response and print out the Access Token
  rsp = JSON.parse(response.body)
  puts "ACCESS TOKEN: #{rsp["token"]}"
  redirect '/home'
end

#post '/callback' do
#  push = JSON.parse(request.body.read)
#  puts "I got some JSON: #{push.inspect}"
#end

When you run your server and click through to authorize the user, you should now also see the "Access Token" output on the terminal:

ruby ssl_server.rb
== Sinatra (v1.4.7) has taken the stage on 4567 for production with backup from Thin
Thin web server (v1.6.4 codename Gob Bluth)
Maximum connections set to 1024
Listening on 0.0.0.0:4567, CTRL+C to stop
[05/May/2016:10:45:32 +0000] "GET / HTTP/1.1" 200 512 0.0041
CODE: XXXXXXXXXXXXXXXXXXXXX
STATE:example
ACCESS TOKEN: YYYYYYYYYYYYYYYYYYYYYYYYYY
[05/May/2016:10:45:36 +0000] "GET /callback?code=XXXXXXXXXXXXXXXXXXXX&state=example HTTP/1.1" 302 - 0.7180
[05/May/2016:10:45:36 +0000] "GET /home HTTP/1.1" 200 12 0.0004

Use your token

Now that we have the authorized token, we can use this to execute some action on behalf of our user. An example query in Ruby is below, using the token with our SDK helper.

> require 'intercom'
 => true
> intercom = Intercom::Client.new(token: '<ACCESS TOKEN>')
> user = intercom.users.find(:user_id => "11")
 => #<Intercom::User:0x000000026a6998 @changed_fields=#<Set: {}>, @custom_attributes={}, @id="571921c8cbc37c3717000004", @user_id="11", @anonymous=false, @email="nietzche@existentialist.com", @name=" Fred", @pseudonym=nil, @avatar=#<Intercom::Avatar:0x000000026a0868 @changed_fields=#<Set: {}>, @image_url=nil>, @app_id="a86dr8yl", @companies=[], @location_data={}, @last_request_at=nil, @last_seen_ip=nil, @created_at=1461264840, @remote_created_at=nil, @signed_up_at=nil, @updated_at=1461933410, @session_count=0, @social_profiles=[], @unsubscribed_from_emails=false, @user_agent_data=nil, @tags=[], @segments=[#<Intercom::Segment:0x0000000266ce00 @id="5720e6ac7175427af100001b", @changed_fields=#<Set: {}>>]>
> user.email
 => "nietzche@existentialist.com"

Use OmniAuth instead

We have added support for Intercom to number of OAuth libraries. It makes the setup process much easier, so it is a good way to setup OAuth for your app:

For Rails apps, use Intercom strategy for OmniAuth.

For Node.js apps, use Intercom Strategy for Passport.

For PHP apps, use Intercom Provider for PHP League's OAuth 2.0.

For GO apps, use GOTH library.
To prevent user impersonation, check that user.RawData["email_verified"] is set to true in the response.


What's Next

Apps in the Messenger will need to complete additional steps which our Setting Up guide details below. Once done, learn how to get your app listed on the Intercom App Store.

Configuring your app
Review & Publish Your App