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.

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

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_url that you specified, with a code query parameter appended to the URL. You'll use that code to get an access token from Retently.

Note: In Retently we don't predefined the redirect_url so you can use any URL from your side that will be contained in the code query.

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

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> 

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

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

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

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