Authorization Using OAuth 2.0

We recommend setting up authorization using OAuth 2.0 to integrate a third-party app with Reteno.

OAuth 2.0 is an authorization protocol that allows third-party apps to securely access certain Reteno data and capabilities without providing user credentials and API keys.

Granting Access Rights to Your Reteno Account

You can restrict access to your resources in Reteno with OAuth 2.0. For example:

• Stripo.email allows only to export email templates to Reteno.
• A CRM (for example, AmoCRM) allows only to add and edit contacts in Reteno when they are changed in the CRM. Or CRM can also receive contact activity data and display it on its own.
• A CMS (for example, Wix) only allows the use of standard subscription forms to add subscribers directly to Reteno.

Access to Reteno resources is determined by the set of permissions (scope) specified during app registration. The available options and corresponding API resources are listed below:

📘

Note

If you change the access scope of an app after registration, already issued tokens will continue to work with the old set of permissions. To get a token with updated permissions, the user must go through authorization again.

Registering, Editing, and Deleting an App in Reteno

Before you start integrating using OAuth 2.0, register your app with Reteno.

App Registration

1. Click on your organization name in the upper right corner and select the For partners tab.

2. Click Register app.

3. Provide app information:

• Name;
• Callback URL – the address to which the service will redirect the user after authorization or authorization refusal (you can create an app without Callback URL and specify it later);
• Select access scopes.

4. Click Register.

After registering, the app will be assigned a Client ID and Client Secret. Write them down and store them in a safe and secure storage facility.

5. Customize the appearance of the authorization form:

• Click Edit;

• Go to the Authorization form tab;
• Enter the app name if needed;
• Upload logo: maximum JPG, GIF, or PNG size is 1 MB; recommended aspect ratio is 1:1 (96×96px); larger images will be cropped to 100% width and center-aligned (you can create an app without a logo and upload it later).

After registering the app, a window with information about it will appear on the Partner apps tab.

Click on the three dots to preview the authorization form or delete the app. Once deleted, all keys/tokens/integrations will become invalid.

Integrating with OAuth 2.0

📘

Note

The implementation is supported only for apps with a server part, i.e., response_type=code.

1. Authorization

Send a GET request to the authorization URL https://uaa.reteno.com/uaa/oauth/authorize.

The request must contain the Client ID received when registering the app in Reteno.

Request format:

https://uaa.reteno.com/uaa/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

Request parameters:

• response_type=code — indicates that this is a request for the authorization page with login and password fields
• client_id — Client ID received when registering the app
• redirect_uri — Callback URL specified when registering the app

As a result, an authorization window will appear.

Enter your Reteno login and password, and confirm access.

The request will be redirected to the Callback URL with the code used to obtain tokens:

HTTP/1.1 302 Found
Location: http://YOUR_CALLBACK_URL?code=YOUR_CODE

2. Obtaining Access and Refresh Tokens

Send a POST request to the Access Token URL https://uaa.reteno.com/uaa/oauth/token.

Request format:

https://uaa.reteno.com/uaa/oauth/token?grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE&redirect_uri=YOUR_CALLBACK_URL

Authentication — Basic Auth: username is your Client ID, password is your Client Secret.

Request parameters:

• grant_type=authorization_code — indicates that this is a request to obtain an access token
• client_id — Client ID received when registering the app
• client_secret — Client Secret received when registering the app
• code — authorization code received in the previous step
• redirect_uri — Callback URL specified when registering the app

In the response, you will receive an Access Token for accessing the Reteno API (access_token) and a Refresh Token for updating the Access Token (refresh_token).

Response format:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "UseRestApi",
  "expires_in": 172800
}

📘

Note

By default, the Access Token is valid for 48 hours and the Refresh Token for 30 days. The countdown starts from the moment the token is created.

3. Calling the API

To call the Reteno API, pass the access token in the header of each request:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

The available API methods are determined by the set of permissions (scope) specified for the app during registration.

4. Refreshing Token

A token can be refreshed at any time. After refreshing, the old access token becomes invalid — only the new one can be used.

Send a POST request to the Access Token URL https://uaa.reteno.com/uaa/oauth/token.

Request format:

https://uaa.reteno.com/uaa/oauth/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Authentication — Basic Auth: username is your Client ID, password is your Client Secret.

Request parameters:

• grant_type=refresh_token — indicates that this is a token refresh request
• refresh_token — the refresh token received in step 2 (or in step 4 if this is not the first refresh)
• client_id — Client ID received when registering the app
• client_secret — Client Secret received when registering the app

The response contains a new access_token and a new refresh_token to be used the next time the access token is refreshed.

5. Authorization Testing

Send a GET request to https://reteno.com/api/v2/version with authorization in the form of the Authorization: Bearer <YOUR_ACCESS_TOKEN> header.

You should see the current API version and API protocol version in the response.

Example of Authorization Using Python

import requests, json

authorize_url = "https://uaa.reteno.com/uaa/oauth/authorize"
token_url = "https://uaa.reteno.com/uaa/oauth/token"
callback_uri = "http://my_host:8081/test/callback"
protected_api_contacts = "https://reteno.com/api/v1/contacts"

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

authorization_redirect_url = authorize_url + '?response_type=code&client_id=' + client_id + '&redirect_uri=' + callback_uri
print("go to the following url on the browser and enter the code from the returned url: ")
print("---  " + authorization_redirect_url + "  ---")
authorization_code = input('code: ')

data = {'grant_type': 'authorization_code', 'code': authorization_code, 'redirect_uri': callback_uri}
print("requesting access token")
access_token_response = requests.post(token_url, data=data, verify=False, allow_redirects=False, auth=(client_id, client_secret))
print("response")
print(access_token_response.headers)
print('body: ' + access_token_response.text)

tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
print("access token: " + access_token)

api_call_headers = {'Authorization': 'Bearer ' + access_token}
api_call_response = requests.get(protected_api_contacts, headers=api_call_headers, verify=False)
print(api_call_response.text)

Connected Apps

Integrated apps are displayed on the Connected apps tab in your organization settings. To disconnect an app, click on the three dots opposite its name and select the appropriate option.