Skip to main content

Authentication

To access the CleverReach REST API, you need an access token. Tokens are tied to specific CleverReach accounts and grant full control over that account's data via the API.

Security Notice

Access tokens provide extensive permissions. Always handle them securely and obtain explicit permission from account owners before using OAuth.

The primary goal of OAuth is to securely obtain a REST API token for controlling a user's account.

OAuth2 Flow for Beginners​

If you're new to OAuth, don't worry! It's like asking for permission to use someone's car. Here's a simple breakdown:

Why OAuth?​

Instead of sharing your password, OAuth lets users grant access without revealing secrets. CleverReach uses it to let your app control their email accounts safely.

Simple Steps​

  1. Register Your App: Create an "OAuth app" in CleverReach (Account > Extras > REST API). Get a Client ID and Secret – these are like your app's ID card.

  2. Ask for Permission: Send users to CleverReach's login page. They log in and approve your app.

  3. Get a Code: After approval, CleverReach sends a temporary code back to your app.

  4. Exchange for Token: Your app trades the code for an access token (like a car key). Use this token in API requests.

  5. Stay Authorized: Tokens expire. Use a refresh token to get new ones without re-approval.

Example in Plain English​

  • You build an app to manage newsletters.
  • User clicks "Connect with CleverReach" in your app.
  • User logs into CleverReach and says "Yes, let this app access my lists."
  • Your app gets a token and can now add subscribers or send emails on their behalf.

OAuth​

Our OAuth implementation follows the 2.0 Specification. For a detailed OAuth explanation please have a look at this introduction to OAuth.

The main approach of OAuth is to get a REST API Token in order to be able to control the users account by using the REST API.

Get started with Authorization Code​

A process to provide to users to retrieve tokens for their accounts.

How to work with OAuth Code in CleverReach®:​

  1. Go to Account > Extras > REST API and create an OAuth app inside of CleverReach®. Note the Client ID and the Client Secret the app contains!

  2. Create a callback page to be called after OAuth process has finished. Place that file on a server to be refereed to as the redirect_uri.

  3. Redirect the user to our OAuth service (see example code) The user will grant you access by logging in to CleverReach®. After the OAuth process finished, the redirect_uri is called.

  4. The redirect_uri - your callback page - is called with a code. Immediately trade this code in for an access token (see example code). Please note, that the code is valid only a few seconds!

This way, all your users can provide you with a token using one OAuth app. It is really easy. Give it a try!

Use the official PHP SDK

If you are developing in PHP, we highly recommend using our official PHP SDK. It includes built-in methods for handling the full OAuth 2.0 flow securely and provides easy ways to acquire and use access tokens without having to perform raw HTTP requests yourself.

Example OAuth process​

We will handle both, the callback page and the page to start from in one php file. Note the if to differ the output. The example is well documented, though to try you do not need to read all the comments. Just fill the variables and go...

OAuth token response​

The final result of the OAuth process is the access token. Here is the format of the reponse as an example.

{
  "access_token": "7h4t1s50mek1nd0fab4t70ken",
  "expires_in": 31536000,
  "scope": "batmobile batcycle batplane batcopter",
  "refresh_token": "m4keb4t70kenfr35h"
}

In case the access_token has expired, you get request a new one by using the refresh_token. The refresh_token therefore has a longer lifetime than the access_token.

Using the refresh token​

In case the access_token is expired, you should take care to retrieve a new one using the refresh_token. To accomplish that, you do a request to POST http://rest.cleverreach.com/oauth/token.php

// Values from your OAuth app.
$clientid     = "#Place OAuth clientID here#";
$clientsecret = "#Place OAuth client secret here#";

// No need to change anything from here.
$token_url = "https://rest.cleverreach.com/oauth/token.php";

$curl = curl_init();
curl_setopt($curl,CURLOPT_URL, $token_url);
curl_setopt($curl,CURLOPT_POSTFIELDS, array(
"grant_type" => "refresh_token",
"refresh_token" => "m4keb4t70kenfr35h",
"client_id" => $clientid,
"client_secret" => $clientsecret
));

curl_setopt($curl,CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
curl_close ($curl);

// The final $result contains the new access_token and some other information.
// For you to see it, we dump it out here.
var_dump($result);