Autenticación

¿Qué es la Autenticación? 🧐

Para activar una API, se debe realizar una autenticación para asegurarse de que los datos procesados estén protegidos. Hay tres métodos principales para hacer esto: autenticación básica HTTP, API y OAuth keys.
En RD Station utilizamos los métodos de autenticación OAuth e Claves de API.

OAuth

Prerrequisitos

Antes de iniciar el proceso de autenticación, comprueba si ya tienes:
✔️ Una cuenta de RD Station. Si aún no tienes una, crea una aquí.
✔️ Una URL de callback para recibir la primera credencial de la cuenta.
✔️ Las credenciales client_id y client_secret

¿Qué es una URL de callback?

En un flujo de autenticación, tu aplicación solicita autorización para tener acceso a una cuenta dentro de la estructura de RD Station. Por lo tanto, necesitamos una "dirección de entrega" de tu aplicación para que podamos devolver esta autorización, en caso de que nuestro cliente autorice la conexión de tu aplicación con RD Station. Esta dirección de entrega es la URL de callback.

Una URL de callback se parece a esto: https://nombredelaapp.org/auth/callback

¿Qué son las Credenciales?

En el flujo de autenticación OAuth, tu aplicación tiene dos credenciales, a las que llamamos client_id y client_secret. Estas credenciales se utilizan para generar tokens de acceso.
Una vez que se genera un token de acceso, este se usa para el intercambio de mensajes a través de la API.

Si aún no tienes estas credenciales, puedes generarlas al acceder a RD Station App Store. Allí podrás realizar el proceso de envío de tu solicitud y, después de eso, se crearán tus credenciales.

Si ya tienes las credenciales, puedes iniciar el proceso de autenticación ahora mismo.

Paso a paso resumido del flujo de autenticación 😉

Paso 1:
Crear una aplicación en RD Station App Store

Paso 2:
Reemplazar los campos de la siguiente URL con los datos que obtendrás de la aplicación.
https://api.rd.services/auth/dialog?client_id={client_id}&redirect_uri={redirect_uri}

Paso 3:
Hacer clic en el link e iniciar sesión en RD Station Marketing.

Paso 4:
Después de iniciar sesión y confirmar el acceso, enviaremos el code a la URL de callback.

Paso 5:
Solicitar el access_token y refresh_token a partir del code generado, al enviar una solicitud a nuestra API.

Paso 6:
¡Listo! Ahora ya puedes enviar datos a nuestra API con el access_token recibido.

Inicio del proceso de autorización

Tu aplicación debe dirigir el usuario a la URL de autorización que se indica a continuación, reemplazando los parámetros client_id y redirect_uri con tus credenciales. Mira el siguiente ejemplo:

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

Verás el cuadro de confirmación de autorización, como se muestra en la siguiente imagen. Haz clic en el botón para confirmar el acceso.

Approved name account es

Una vez realizada la confirmación, RD Station enviará una URL de callback, que contiene el parámetro code.
Mira el ejemplo:

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

Este proceso solo debe realizarse una vez \O/

Sin embargo, puede repetirse si deseas generar un nuevo code o si el usuario está desconectado.

Nota: Si la URL de callback posee query string, el valor debe pasarse en formato encoded.
Ejemplo:

  Url de callback: http://example.com/callback/index?name=auth
  Url de callback encoded: http%3A%2F%2Fexample.com%2Fcallback%2Findex%3Fname%3Dauth

Obtención de tokens de acceso

Una vez que se recibe el parámetro code, solo falta obtener el token de acceso. Para eso, solo debes realizar una solicitud para obtener el access_token:

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

Obtención de tokens de acceso

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

Con el access_token generado, este debe enviarse en el encabezado de cada solicitud a la API pública.

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

Actualización de un token caducado

Cada access_token es temporal y tiene como plazo de caducidad el valor definido por el atributo expires_in en segundos, que es 86.400 segundos (24 horas).

Se genera un nuevo access_token usando el refresh_token, ejemplo:

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

Actualización de un token caducado

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

Cancelación del acceso de un token

El acceso de los clientes con autenticación de tipo OAuth se puede cancelar siempre que sea necesario.
Esto se puede hacer usando el access_token o refresh_token, por ejemplo:

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

Cancelación del acceso de un 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

El uso de la clave API permite enviar eventos de conversión a RD Station Marketing.
La clave API es un token que debe enviarse a través de Query String utilizando el parámetro api_key.

Para más información sobre las API Keys, ingresa a la Central de Ayuda.

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

Evento de Conversión

RD Station Marketing considera el valor del atributo conversion_identifier como el identificador de conversión.
Este evento es registrado cada vez que se produce una conversión.

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