Authentication for your integration starts with login on your Retently account. You'll use the Client ID and Client Secret to initiate the OAuth handshake between Retently and your integration.

OAuth 2.0 overview

There are 4 main steps to connecting your integration to a Retently account using OAuth:

  1. Build the authentication URL for your app, and send the Retently user to that URL. After the user grants access, they'll be returned to your app, with a code appended to the URL. 
  2. Use that code and your Client Secret to get an access_token and refresh_token.
  3. Use that access_token to authenticate any API calls that you make for that Retently account.
  4. Once that access_token expires, use the refresh_token from Step 2 to generate a new access_token.

Initiate an integration with OAuth 2.0

In order to initiate OAuth access for your Retently app, you'll first need to send a Retently user to an authorization page, where that user will need to grant access to your app.  When your app sends a user to that authorization page, you'll use the query parameters detailed below to identify your app.

Initiating an OAuth connection requires that you have a Retently account. The Client ID that you'll need to include in the authorization URL can be found in the OAuth application details form, which you can get to by clicking the OAuth link under the Integrations menu item.

Users must be signed into Retently to grant access, so any user that is not logged into Retently will be directed to a login screen before being directed back to the authorization page. The authorization screen will show the details for your app.

After the user grants access, they will be redirected to the redirect_uri that you specified, with a code query parameter appended to the URL. You'll use that code to get an access token from Retently.

Method details:
URL: https://app.retently.com/api/oauth/authorize
HTTP Method: GET
Headers: -
Response Format: -

Example. Authorization URL

Sending a user to this URL will ask the user to approve access to contacts and workflows:
https://app.retently.com/api/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&redirect_uri=https://www.example.com/&response_type=code 

If they grant access, the user would be redirected to this URL:
https://www.example.com/?code=xxxx 

If there are any problems with the authorization, you'll get the error parameters instead of the code:
https://www.example.com/?error=error_code&error_description=<A human readable error message> 

Get OAuth 2.0 Access Token and Refresh Tokens

Use the code you get after a user authorizes your app to get an access token and refresh token.  The access token will be used to authenticate requests that your app makes.  Access tokens expire after 6 hours, so you can use the refresh token to get a new access token when the first access token expires.

Method details:
URL: https://app.retently.com/api/oauth/token
HTTP Method: POST
Headers:
    Content Type: application/x-www-form-urlencoded
Response Format: json

Example. Access Token and Refresh Tokens

POST URL: https://app.retently.com/api/oauth/token
Headers:
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
Data:
grant_type=authorization_code&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&redirect_uri=https://www.example.com/&code=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

If successful, you will receive a JSON response with the tokens:
{
    "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "refresh_token": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "expires_in": 21600
}

If there are any problems with the request, you'll receive a 400 response with an error message.
{
    "error": "error_code",
    "error_description": "A human readable error message"
}

Refresh OAuth 2.0 Access Token

Use a previously obtained refresh token to generate a new access token.  Access tokens expire after 6 hours, so if you need offline access to data in Retently, you'll need to store the refresh token you get when initiating your OAuth integration, and use that to generate a new access token once the initial access token expires.

Method details:
URL: https://app.retently.com/api/oauth/token
HTTP Method: POST
Headers:
    Content Type: application/x-www-form-urlencoded
Response Format: json

Example. Refresh OAuth 2.0 Access Token

POST URL: https://app.retently.com/api/oauth/token
Headers:
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
Data:
    grant_type=refresh_token&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&redirect_uri=http://www.example.com/&refresh_token=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

If successful, you will receive a JSON response with a new access_token:
{
    "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "refresh_token": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
    "expires_in": 21600
}

If there are any problems with the request, you'll receive a 400 response with an error message.

{
    "error": "error_code",
    "error_description": "A human readable error message"
}

  • Login to your Retently account;
  • From left sidebar (menu), under Integration menu item, click on OAuth link;
  • Copy OAuth Client ID and Client secret;
  • Open Postman;
  • Select method, for example GET, and fill in Retently API endpoint, for example https://app.retently.com/api/v2/nps/customers More details about Retently API can be found here https://www.retently.com/api/
  • From Authorization tab, select type OAuth 2.0;
  • Click on Get New Access Token button;
  • Fill in mandatory fields:
       
    *Token Name: Retently OAuth
       
    *Grant Type: Authorization Code
        *Callback URL: <your callback>
        *Auth URL: https://app.retently.com/api/oauth/authorize
        *Access Token URL: https://app.retently.com/api/oauth/token
        *Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
        *Client Secret: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
        *Client Authentication: Send client credentials in body
  • Click on Request Token button
  • Fill in your Retently account credentials - email and password.
  • Grants access
  • Done!

Did this answer your question?