Authentication

What is authentication? 🧐

Before an API can be requested, you must perform an authentication to ensure that the data being exchanged is protected. There are three main methods to do this: Basic HTTP authentication, API keys and OAuth.
In RD Station we use OAuth and API Keys authentication methods.

OAuth

Prerequisites

Before starting the authentication process, check to see if you already have:
✔️ An RD Station account. If you don't already have one, create one here.
✔️ A callback URL to receive the first account credentials.
✔️ client_id and client_secret credentials.

What is a callback URL?

In an authentication flow, your application requests authorization to access an account within RD Station. Therefore, we need a "delivery address" of your application to return this authentication if our client authorizes the connection of your tool with RD Station. This delivery address is the callback URL.

A callback URL looks like this: https://appname.org/auth/callback

What are credentials?

In the OAuth authentication flow, your application has two credentials, which we call client_id and client_secret. These credentials are used to generate access tokens.
Once an access token has been generated, it will be used in message exchanges made via API.

If you don't have these credentials, you can generate them by accessing the RD Station App Store. This is where you will submit your application. After that your credentials will be created.

If you already have the credentials, you can start the authentication process now.

Brief step-by-step authentication flow guide 😉

Step 1:
Create an app in the RD Station App Store

Step 2:
Replace the URL fields below with the data you will get from the application.
https://api.rd.services/auth/dialog?client_id={client_id}&redirect_uri={redirect_uri}

Step 3:
Click on the link and log in to RD Station Marketing.

Step 4:
After login and access confirmation, we will send the code to the callback URL.

Step 5:
Request the access_token and refresh_token from the code generated by sending a request to our API.

Step 6:
Done! You can now send data to our API with the access_token received.

Starting an authorization flow

Your application must direct the user to the authorization URL shown below, replacing the parameters client_id and redirect_uri with their credentials. See the example below:

GET https://api.rd.services/auth/dialog?client_id={client_id}&redirect_uri={redirect_uri}

Request Parameters:

client_id	Type: String	Client
redirect_uri	Type: String	Redirect Uri

You will see the authorization confirmation box as shown in the image below. Click the button to confirm access.

Approved name account en

Once confirmed, RD Station will return with a callback URL, which contains the code parameter.
See the example below:

https://yourapp.org/auth/callback?code={code}

This process only needs to be done once \O/

However, it can be repeated if you want to generate a new code or if the user is disconnected.

Note: If the callback URL has a query string, the value must be passed in encoded format.
Example:

  Callback url: http://example.com/callback/index?name=auth
  Encoded callback url: http%3A%2F%2Fexample.com%2Fcallback%2Findex%3Fname%3Dauth

Getting access tokens

Once you have the code parameter, you just need the access_token. To do this, simply make a request to obtain the access_token:

POST https://api.rd.services/auth/token

Getting access tokens

Request Parameters

client_id	Type: String	Client
client_secret	Type: String	Client Secret
code	Type: String	Code

Body Example:

          {
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code": "CODE"
}

Response Body Parameters

access_token	Type: String	Access Token
refresh_token	Type: String	Refresh Token
expires_in	Type: Integer	Expires In

Response Example:

          {
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5UZ3hRamM1UWpKR1FUUkNPRVE0UVRZeFJFVTBNRFEzUkRGRE9UVXdPVE5FTXpVM09UUXpRUSJ9.eyJpc3MiOiJodHRwczovL3Jkc3RhdGlvbi5hdXRoMC5jb20vIiwic3ViIjoidklUYjF2N0NoVmhmUVE2QUFTbDNLVUpYRUJTSVNCR2hAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXBwLnJkc3RhdGlvbi5jb20uYnIvYXBpL3YyLyIsImV4cCI6MTUwNDI5NDQzMSwiaWF0IjoxNTA0MjA4MDMxLCJzY29wZSI6IiJ9.k7OSdhOlTgRBZmEhg_uXXaCofEq4iwDdBi6yuD8SxMF06nCA834KjIqWkmX-W-u84q8SEzGyhb_KT0zZlMvyGotoGPMry_vABXEIorC25zKCUE9BtMJpHJ_suFwQMqZQ8rK6JSnbkOKwLuuDq8_YnrutBURJiBSdSI9325MLw0DZdnw0IgXnNVCHRLdOMl4k_Ovk5Ke3yzESJvMxgJJ3UnojL0ckRExVPwxnbLCyJp1W_PsEe-FOcEl0kDEX-8JQ8MGATiB2vZOu5TJi4sbYCLzg3GInegGh9zvZQR1W4K3isDtOmlNRSYU9A5ez3dQ8HTZdCj9gT_aGWWskxWi6Cw",
  "expires_in":86400,
  "refresh_token":"9YORmXHgOI32k-Y22tZWm-rsf--oFPr8JDCQIQhBEUY"
}

cURL example request:

    
 curl --request POST --url 'https://api.rd.services/auth/token' --header 'Content-Type: application/json' --data '{ "code": "dbexxxxxxxxxxxxxxx865", "client_id": "5c6xxxxxxxxxxxxxxxacc",  "client_secret":"LzHxxxxxxxxxxxxxxx98V"}'

With the access_token generated, it must be sent in the header of each request to the Public API.

`Authorization: Bearer access_token`	Required on client request
`Content-Type: application/json`	Required on client request

Refreshing an expired token

Every access_token is temporary, and its expiration time is defined by the expires_in attribute in seconds, which is 86400 seconds (24 hours).

A new access_token is generated using refresh_token. Example:

POST https://api.rd.services/auth/token

Refreshing an expired token

Request Parameters

client_id	Type: String	Client
client_secret	Type: String	Client Secret
refresh_token	Type: String	Refresh Token

Body Example:

          {
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN"
}

Response Body Parameters

access_token	Type: String	Access Token
refresh_token	Type: String	Refresh Token
expires_in	Type: Integer	Expires In

Response Examples:

Success - 200 Ok

          {
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5UZ3hRamM1UWpKR1FUUkNPRVE0UVRZeFJFVTBNRFEzUkRGRE9UVXdPVE5FTXpVM09UUXpRUSJ9.eyJpc3MiOiJodHRwczovL3Jkc3RhdGlvbi5hdXRoMC5jb20vIiwic3ViIjoidklUYjF2N0NoVmhmUVE2QUFTbDNLVUpYRUJTSVNCR2hAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXBwLnJkc3RhdGlvbi5jb20uYnIvYXBpL3YyLyIsImV4cCI6MTUwNDI5NDQzMSwiaWF0IjoxNTA0MjA4MDMxLCJzY29wZSI6IiJ9.k7OSdhOlTgRBZmEhg_uXXaCofEq4iwDdBi6yuD8SxMF06nCA834KjIqWkmX-W-u84q8SEzGyhb_KT0zZlMvyGotoGPMry_vABXEIorC25zKCUE9BtMJpHJ_suFwQMqZQ8rK6JSnbkOKwLuuDq8_YnrutBURJiBSdSI9325MLw0DZdnw0IgXnNVCHRLdOMl4k_Ovk5Ke3yzESJvMxgJJ3UnojL0ckRExVPwxnbLCyJp1W_PsEe-FOcEl0kDEX-8JQ8MGATiB2vZOu5TJi4sbYCLzg3GInegGh9zvZQR1W4K3isDtOmlNRSYU9A5ez3dQ8HTZdCj9gT_aGWWskxWi6Cw",
  "expires_in":86400,
  "refresh_token":"9YORmXHgOI32k-Y22tZWm-rsf--oFPr8JDCQIQhBEUY"
}

Invalid Grant - 401 Unauthorized

Response Headers

WWW-Authenticate: Bearer realm="https://api.rd.services/", error="invalid_grant", error_description="The provided refresh token is invalid or was revoked."

Response Body

          {
  "error_type": "INVALID_REFRESH_TOKEN",
  "error_message": "The provided refresh token is invalid or was revoked."
}

cURL example request:

            
  curl --request POST --url 'https://api.rd.services/auth/token' --header 'Content-Type: application/json' --data '{ "refresh_token": "OlzExxxxxxxxxxxxxxx-379", "client_id": "5c6xxxxxxxxxxxxxxxacc",  "client_secret":"LzHxxxxxxxxxxxxxxx98V"}'

Revoking access token

Client access with OAuth authentication type can be revoked whenever needed.
This can be done using access_token or refresh_token. Example:

POST https://api.rd.services/auth/revoke

Revoking access token

Request Headers

Content-Type	x-www-form-urlencoded
Authorization	Bearer ACCESS_TOKEN

Request Parameters

Field	Type	Required	Description
token	String	true	Refresh Token Or Access Token
token_type_hint	String	false	Available Options

Body Example:

          {
  "token": "REFRESH_TOKEN",
  "token_type_hint": "refresh_token"
}

cURL example request:

            
  curl --request POST --url 'https://api.rd.services/auth/revoke' --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: Bearer ACCESS_TOKEN' --data '{ "token": "OlzExxxxxxxxxxxxxxx-379", "token_type_hint": "refresh_token"}'

API Key

The use of API Key makes it possible to send conversion events to RD Station Marketing.
API key is a token that must be sent via Query String using the api_key parameter

To learn more about API Keys go to Help Center.

Default Headers

Request Headers

Content-Type	application/json

Query String

Authentication Token

Query Param	api_key

Default Responses

Responses structure:

Success | Code: 200

{
  "event_uuid": "5408c5a3-4711-4f2e-8d0b-13407a3e30f3"
}

Bad Request | Invalid Event Type | Code: 400

{
  "errors": [
    {
      "error_type": "INVALID_OPTION",
      "error_message": "Must be one of the valid options.",
      "validation_rules": {
        "valid_options": [
          "CONVERSION"
        ]
      },
      "path": "$.event_type"
    }
  ]
}

Conversion Event

RD Station Marketing considers the value of the conversion_identifier attribute as the conversion identifier.
This event is recorded whenever a conversion occurs.

POST https://api.rd.services/platform/conversions?api_key=[api-key-token]

Request body parameters

Field	Type	Required	Description
event_type	String	true	The event type that diferentiates the event. For the conversion event it should be sent as "CONVERSION".
event_family	String	true	The family of the event for processing purposes. It currently accepts only "CDP" as valid option.
conversion_identifier	String	true	The name of the conversion event.
name	String	false	Name of the contact.
email	String	true	Email of the contact.
job_title	String	false	Job title of the contact.
state	String	false	State of the contact.
city	String	false	City of the contact.
country	String	false	Country of the contact.
personal_phone	String	false	Phone of the contact.
mobile_phone	String	false	Mobile phone of the contact.
twitter	String	false	Twitter handler of the contact.
facebook	String	false	Facebook of the contact.
linkedin	String	false	Linkedin of the contact.
website	String	false	Website of the contact.
company_name	String	false	Company name of the contact.
company_site	String	false	Company website of the contact.
company_address	String	false	Company address of the contact.
client_tracking_id	String	false	Value of a '_rdtrk' cookie. (e.g: 43b00843-09af-4fae-bf9d-a0697640b808)
traffic_source	String	false	This can either be the value of a '__trf.src' cookie (base 64 encoded or not) or an UTM source param. If passing a cookie the following fields MUST be empty: traffic_medium, traffic_campaign and traffic_value.
traffic_medium	String	false	UTM medium param.
traffic_campaign	String	false	UTM campaign param.
traffic_value	String	false	UTM value param (term).
tags	Array of Strings	false	Tags that can be added to the contact.
available_for_mailing	Boolean	false	Enable/disable receive emails.
legal_bases	Array of Objects	false	Legal Bases of the contact.
cf_custom_field_name*	String	false	Custom field created in RDSM and its value related to the contact.

* All custom fields available in RD Station Marketing account are valid on this payload. They should be sent using the prefix "cf_" plus the field name, for instance: cf_age.

Request body example

{
  "event_type": "CONVERSION",
  "event_family":"CDP",
  "payload": {
    "conversion_identifier": "Name of the conversion event",
    "name": "name of the contact",
    "email": "email@email.com",
    "job_title": "job title value",
    "state": "state of the contact",
    "city": "city of the contact",
    "country": "country of the contact",
    "personal_phone": "phone of the contact",
    "mobile_phone": "mobile_phone of the contact",
    "twitter": "twitter handler of the contact",
    "facebook": "facebook name of the contact",
    "linkedin": "linkedin user name of the contact",
    "website": "website of the contact",
    "company_name": "company name",
    "company_site": "company website",
    "company_address": "company address",
    "client_tracking_id": "lead tracking client_id",
    "traffic_source": "Google",
    "traffic_medium": "cpc",
    "traffic_campaign": "easter-50-off",
    "traffic_value": "easter eggs",
    "tags": ["mql", "2019"],
    "available_for_mailing": true,
    "legal_bases": [
      {
        "category": "communications",
        "type": "consent",
        "status": "granted"
      }
    ],
    "cf_my_custom_field": "custom field value"
  }
}