OAuth - Authorization Code

OAuth is the preferred authentication method for partners. Partner Applications submitted using API Keys will not be approved.

Salesloft uses OAuth 2.0 authorization flow to generate access tokens that your application can use against the API. Follow the steps below to gain access.

Create an OAuth App

You can create apps via Salesloft Account → Your Applications → OAuth Applications → Create New.

 

1. Upload your Logo - SVGs with a 1:1 aspect ratio
2. Fill out the blank fields -
   • Name - Name of your App
   • Description - Description of your app shown to the user turning on your integration
   • Redirect URI - The url a user is sent back to after completion of a successful authorization. This is a non-Salesloft url.
3. Application Type - Will this app be published as a public Frontend Integration?
   • Yes - this will be a public application
   • No - this will be a private team application
4. Grant Type - What grant type will this application be using?
   • Authorization Code- recommended for applications that require end users to authorize.
5. Scopes - Select the scopes relevant to your application by clicking the checkmark next to the scope.
   • Scopes - relates to the data and actions an application can perform
   • Privileged Scopes - scopes that can access sensitive data

6. Click Submit
7. You will now see a screen with your:
   • Description
   • Application Id(Client Id)
   • Integration Id
   • Secret(Client Secret)
   • Application Type
   • Grant Type
   • Scopes
   • Privileged Scopes
   • Allowlisting App
   • Allowlist Status

 

Your Application Id, Secret and Redirect URI will be needed for the next steps in the Authorization process.

Editing an OAuth App

Go to Your Applications → OAuth Applications → Edit to edit your application.

You have the ability to edit all parts of your application except for the Application Type and Grant Type.

Obtain Authorization Code​ & Grant Access to Your App

At Salesloft, one of the methods we use to access our Public API is the Authorization code grant type. You will need to first generate a request to our authorization endpoint with your Application Id(Client Id). This endpoint will be displayed to the end user (if they haven't already accepted your application) and they can either approve or deny your application on setup.

Option 1:

Click the Test Authorization button (underneath the Redirect URIs section) and then click Authorize. On reload, take note of the code parameter in the address bar after your redirect url.

Example: test.com/?code=12145546...

Option 2:

Click and/or copy and paste the link below and replace YOUR_CLIENT_ID and YOUR_REDIRECT_URI with the appropriate values from your application in the address bar and hit Enter.

REDIRECT ENDPOINT

https://accounts.salesloft.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code

The following screen should appear prompting you to Authorize or Deny the application.

Obtain Access and Refresh Tokens​

Upon approval, your redirect_uri is redirected and returned with a code and code value.

Example: test.com/?code=12145546...

You must then do a POST request to our server to get an access and refresh token.

POST https://accounts.salesloft.com/oauth/token

{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "YOUR_CODE_VALUE",
    "grant_type": "authorization_code",
    "redirect_uri": "YOUR_REDIRECT_URI"
}

You will get a JSON response back containing the identifying tokens and refresh token information(take note of this). Note that expires_in value is seconds.

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "scope": "accounts:write calls:read",
    "created_at": 1448987410
}

Troubleshooting

If you receive this error:

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request"
}

• Check that the request parameters are in the body and not the header
• Make sure the Headers include a “Content-Type”:”application/json”
• You may need to generate a new authorization code by repeating the steps in the Obtain Access and Refresh Tokens section. Take note of your refresh token.
• Double check all of the variable values match the application you created
• If you are using Postman, double check that the body section is set to x-www-form-urlencoded

Use Refresh Token

When you receive a notification that your access token has expired, you can use a refresh token to get a new one without prompting the user.

POST https://accounts.salesloft.com/oauth/token

{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "refresh_token",
    "refresh_token": "A_REFRESH_TOKEN"
}

This will return the same information as obtaining a token through an authorization grant.

Upon receipt of a refresh token, all old refresh tokens are revoked. In this way, if you perform a refresh, you must store the new refresh_token for future use.

Authorizing Requests

All requests that go to the Salesloft API will need the Authorization header set to Bearer YOUR_ACCESS_TOKEN. As the access_token is only good for a limited period, you must use the refresh token to generate a new access_token when prompted.

Passing up a refresh token will not allow access to the API. You must use the access token.

If sending JSON payloads ensure you set the Content-Type header to application/json.