Outreach app token

When you need to make calls to Outreach on behalf of your app or validate app related calls from Outreach to your server you will need to create an app token. For generating the app token you should first enable S2S API access feature for your app. Once S2S API access is set up, Outreach will generate the value of S2S_GUID used in the app token creation.

Generating app token

The app token is a JWT token that you can generate by using your private key and the S2S_GUID like so:

Copy

Copied

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")

Get S2S access token

S2S access token allows you to call Outreach REST API on behalf of your app. To get the S2S access token collect a value for INSTALL_ID during application setup or from an app lifecycle webhook and then call the accessToken endpoint providing your APP_TOKEN:

Copy

Copied

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 and should be then refreshed using the above method.Note that the accessToken request will fail if the Outreach organization has been locked or deleted by Outreach. When the organization has been fully deleted, you will be notified via webhook.

Get installation information

If your app uses external configuration setup URL you will want to make sure that the incoming user was indeed redirected from Outreach. Before redirecting to your app homepage URL Outreach appends a installSetupToken query which you can utilize for validation. Collect the installSetupToken value and call the setupToken endpoint passing your app token:

Copy

Copied

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 1.0 formatted payload with an install type as its primary data which uniquely identifies your app installation within a specific org.

Copy

Copied

{
  "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"
        }
      }
    }
  }
}

Appending include=app,org query parameter to the endpoint URL will expand the response payload to contain more information about the app and the org. Note that the org relationship will also include a link to that customers API endpoint.