OAuth2 for Contactually

In an effort to allow as many organizations as possible to build on the strength of our user’s relationships, Contactually supports the registration of 3rd party applications, and the authorization of those applications by our users to act on their behalf using an established protocol called OAuth2.

Register a New Application View Your API apps

OAuth2

Application Flow

  1. Link to Contactually to request access. Using the method below, construct a standard link. Contactually will request permissions for your app and the user will have the opportunity to sign up for a new account or sign in with their existing account.

  2. Contactually redirects back to your application. Once the user accepts (or rejects) your authorization request, Contactually redirects back to your application. If you requested a grant response type, you’ll receive a code, if you requested a token response type, you’ll get a token. You should also receive the state (if provided) from the initial URL (round-tripping the same values). If the states don’t match, the request may have been created by a third party and the process should be aborted. If you received a token response, your token is “live” and may be used for requests. If you received a code response, please proceed to step 3.

  3. Exchange the code for an access token. If everything looks good in step 2, exchange the code for an access token using the GET /oauth2/token method. Save the access_token so your app can authenticate the user by sending the Authorization header as indicated above.


Authorize

GET https://auth.contactually.com/oauth2/authorize?scope=user:basic&redirect_uri=https:/example.com/oauth/callbacks/contactually&response_type=code

Authorize Application
GET/oauth2/authorize{?scope,redirect_uri,response_type}

Construct the redirect to this URL. Contactually will request permissions for your app and the user will have the opportunity to sign up for a new account or sign in with their existing account.

Valid scope Options

Option Notes
all:view
all:manage
user:login Only returns user identifier, name, and email. This permission is included by default
user:basic This is the base required to manage notifications, followup reminders, etc.
user:manage Required to update the user (change name, email, etc.)
buckets:manage
buckets:view
contacts:manage
contacts:view
interactions:manage
interactions:view
message-templates:manage
message-templates:view
notes:manage
notes:view
tasks:manage
tasks:view

Multiple scopes can be requested at the same time, separated by +, e.g. (user:login+contacts:view).

The 🔒 below is used to indicate the required scoping to execute certain requests. If your application does not have the required permissions, you can request them at any time.

Please note that a user could revoke your permissions at any time via their settings, your application should handle 403 responses for all requests.

URI Parameters
HideShow
client_id (required, string, `YOUR_ID_HERE`)
string (required) 

Get this from your app settings.

scope
string (required) Example: user:basic

Scope from the list of options registered for your application

redirect_uri
string (required) Example: https://example.com/oauth/callbacks/contactually
response_type
string (required) Example: code

Token

Once a user has authorized your application, and Contactually has returned the code, you’ll need to exchange that code along your client_id, client_secret, and grant_type.

POST https://auth.contactually.com/oauth2/token
Requestsexample 1
Headers
HideShow
Content-Type: application/json
Body
{
  "grant_type": "authorization_code",
  "client_id": "Dvh1fTXzbn0vfHtk4FjBoIxpEPitcflWXBf3wgnnfQG1XTEVvxQv4bu5FfJjLIa1",
  "client_secret": "TsE6rLuAc5HzhEjr7aj1oDWNs6sXTwqj9Auv0JADLO8xanAn7JcCJu3uJLWHlsl8",
  "code": "sy1FVeDjpiIJ2zVZeT1ckO1MDR7Vw46ZMQrNJ0fBILNEF7BbNVHuOXYocAmxKoBX",
  "redirect_uri": "https://secure.example.com/oauth2/callbacks/contactually"
}
Responses200
Body
{
  "access_token": "1C26tVLXJtjRH26w4IpCDOqxjsWkMZXpDwQUhTofujSWepAqq2ZpLNqQPzlC8W78",
  "email": "jsmith@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "token_type": "bearer",
  "user_id": 8
}

Create Token
POST/oauth2/token


POST https://auth.contactually.com/oauth2/token/exchange
Requestsexample 1
Headers
HideShow
Content-Type: application/json
Body
{
  "api_key": "78fpzvh7nylxdwts946zsqbkpta9wmtw",
  "client_id": "Dvh1fTXzbn0vfHtk4FjBoIxpEPitcflWXBf3wgnnfQG1XTEVvxQv4bu5FfJjLIa1"
}
Responses200
Body
{
  "access_token": "1C26tVLXJtjRH26w4IpCDOqxjsWkMZXpDwQUhTofujSWepAqq2ZpLNqQPzlC8W78",
  "scopes": "user:basic"
}

Exchange Existing API Token for New OAuth2 Token
POST/oauth2/token/exchange

If you already have a v1 application that you’re updating to use v2 (and OAuth), you’ll need to exchange your api_key for an OAuth2 access_token.

This request will automatically grant you access with the scopes you’ve set your app to request.


Generated by aglio on 23 Sep 2017