Accessing Outreach REST API from server

When querying Outreach API from server it may be impractical to use OAuth because it needs the interactive login and consent flow. Therefore, Outreach also provides an alternative way for obtaining a token. However the set of endpoints and operations accepting this token is very limited. We refer to this token as "S2S" in short.

Available endpoints and operations

The S2S token does not contain identity of any user. It contains identity of your application and is issued for a particular organization that has your app installed by org admin. That is unfortunately a complication for many endpoints that require a user as an actor.

In general, read operation on available endpoints works well. Some write operations will require your app to provide more data (e.g. an id of an authorizer user) than when the same operation would be called with OAuth token and some write operation might not work at all.

Available scopes:

• accounts - all, delete, read, write
• auditLogs - read
• calls - all, delete, read, write
• events - all, read, write
• mailings - read
• opportunities - all, delete, read, write
• prospects - all, delete, read, write
• sequences - all, delete, read, write
• sequenceStates - all, delete, read, write
• snippets - read
• tasks - all, delete, read, write
• templates - read
• users - read
• webhooks - all, delete, read, write

Enabling S2S API access

Add the "API Access (S2S)" feature for your app in Outreach Developer portal and select one or more API scopes that your application intends to consume. S2S API scopes are a subset of OAuth API scopes.

Then add one or more public keys in PEM-encoded format. You can generate a pair of private and public keys using openssl or similar tool.

openssl genrsa -out outreach_private_key.pem 2048
openssl rsa -in outreach_private_key.pem -outform PEM -pubout -out outreach_public_key.pem

Please, be very careful to not accidentally disclose the private key. If disclosed, it should be replaced immediately.

After you save the page Outreach will generate the S2S_GUID for your app.

Calling the API through S2S

To make server calls to the Outreach REST API you need to obtain an S2S token. A separate S2S token is issued for every app installation and so to generate the S2S token you'll need to learn first and then submit INSTALL_ID - the app installation identifier.

There are two ways how your service can obtain the installation ID:

• synchronously and interactively - once the org admin installs your application to their org Outreach redirects the browser to your service and passes installSetupToken . You shall use the token to obtain the installation ID and you can let the user configure anything on your side.
• asynchronously - once the org admin installs your application to their org Outreach backend calls you webhook endpoint and passes the installation details.

You are supposed to setup at least one of the methods for you app, see External configuration setup URL or Application lifecycle webhooks

Preparing the app token

To obtain S2S token, or to obtain installation ID from installSetupToken you need to create an app token first. The app token authenticates your app to Outreach and you generate it using your private key and the S2S_GUID in this way:

payload = {
  iat: Time.now.to_i,
  exp: Time.now.to_i + 3_600,
  iss: "S2S_GUID",
}
secret = OpenSSL::PKey::RSA.new("PRIVATE_KEY")
app_token = JWT.encode(payload, secret, "RS256")

Obtaining installation ID

If you have got installSetupToken you need to call /api/app/installs/.../actions/setupToken endpoint within 15 minutes in this way:

curl https://api.outreach.io/api/app/installs/INSTALL_SETUP_TOKEN/actions/setupToken \
  -X POST \
  -H "Authorization: Bearer APP_TOKEN"

Outreach will respond with a JSON API formatted payload with an install type as its primary data which uniquely identifies your app installation within a specific org.

{
  "data": {
    "type": "install",
    "id": "INSTALL_ID",
    "attributes": {
      "installedAt": "2019-01-01T00:00:00"
    },
    "relationships": {
      "app": {
        "data": {
          "type": "app",
          "id": "S2S_GUID"
        }
      },
      "org": {
        "data": {
          "type": "org",
          "id": "ORG_ID"
        },
        "links": {
          "api": "https://app1c.outreach.io/api/v2"
        }
      }
    }
  }
}

If you configured Application lifecycle webhooks you can see the expected payload with installation ID documented there, it's almost the same, at least the installation ID is at the same path.

Obtaining S2S token

S2S access token allows you to call Outreach REST API on behalf of your app. To get the S2S access token call the /api/app/installs/.../actions/accessToken endpoint providing your APP_TOKEN and INSTALL_ID that you obtained in previous steps.

curl https://api.outreach.io/api/app/installs/INSTALL_ID/actions/accessToken \
  -X POST \
  -H "Authorization: Bearer APP_TOKEN"

This call returns a JSON response. The path data.meta.accessToken will contain your S2S token. The S2S token remains valid for one hour. There is no token refresh method like OAuth token have, you simply request a new S2S token.

Note that the accessToken request will fail if the Outreach organization has been locked or deleted by Outreach or the admins uninstalled your app. When the organization has been fully deleted or the org admins uninstalled the app, you will be notified via webhook. Unfortunately there is no similar signal on locking the application.

Calling Outreach API with S2S token

Once you have obtained your S2S token pass it in the Authorization header of your call. For example to get all the events for the prospect use:

curl -i -X GET https://api.outreach.io/api/v2/prospects \
  -H "Authorization: Bearer S2S_TOKEN"