All Collections
Retently API
Retently OAuth guidelines
Retently OAuth guidelines
Alex Bitca avatar
Written by Alex Bitca
Updated over a week ago

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_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: -

Example. Authorization URL

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

  • Fill in your Retently account credentials - email and password.

  • Grants access

  • Done!

Did this answer your question?