API access

OAuth in a nutshell

OAuth 2.0 is a standard authorization protocol and there is a lot of information online on how to implement it. Here is how it works in a nutshell:

1. Once you need to connect to Outreach in your own application, you redirect the user to an URL like https://api.outreach.io/oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=....
2. At the authorization page user is informed about which data your application intends to use and gives their consent to do so.
3. Following the consent Outreach redirects the user to the URL on your server passing along a code query parameter also known as the Authorization Grant.
4. You use the Authorization Grant to obtain the Access Token.
5. With the Access Token you call the Outreach REST API endpoints. Outreach will execute all the calls on behalf of the user who performed authorization.
6. Access token is valid for limited period only but you can refresh it using the refresh token returned in the same response.

Setting up OAuth

To begin using the REST API you need to create an Outreach app. Then go to the API access tab to configure access specifics. You'll need to specify one or more redirect URI's and select the OAuth data scopes that your application intends to use. Please select at least one scope and specify at least one redirect URI.

OAuth credentials

For each Outreach app, the development and production credentials are generated.

• Development credentials are provisioned immediately and are intended to be used during application development and testing. Any change (e.g. to scopes) is applied immediately on save. The authorization page warns users that they are using development and unreviewed application and usage of development version is limited. Do not let your end-users use these development credentials.
• Production credentials are provisioned after the app goes through the publishing process and eventually a review. The scopes and URLs are updated when you click on the Publish button.

Limitations of development credentials

If an end-user goes through OAuth flow that contains development credentials they will be warned that the application is not production ready.

Application's development credentials can be authorized by any user from any org. However, the development credentials are meant for developers and testers only. We do not impose any arbitrary block to enforce fair usage but we expire the grant provided by users and revoke all tokens, so users need to re-authorize the app once in a while.

Development credentials are usable with no limitation for up to 10 people from the organization that owns the app.

Users from other orgs or when there are more users from the owning org will need to reauthorize the app weekly.

Requesting access token

curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d redirect_uri=<redirect_uri> \
  -d grant_type=authorization_code \
  -d code=<authorization_grant>

This call will only be successful if all of the parameter values match exactly the values which initiated this OAuth flow.

In some situations you may need to set up different redirect URIs for development and production client IDs so that you know which credential (prod or dev) you need to use in the above call.

  https://api.outreach.io/oauth/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code&scope=<scope1+scope2>&state=dev

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "EcC-5gWjbN...",
  "scope": "users.read",
  "created_at": 1706289101
}

Refreshing access token

curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh_token>