Autenticação

O que é Autenticação

Para que uma API possa ser acionada é preciso realizar uma autenticação para garantir que os dados transacionados estejam protegidos. Existem três métodos principais para fazer isso: autenticação básica HTTP, Chaves da API e OAuth.
No RD Station utilizamos os métodos de autenticação OAuth e Chaves de API sendo este segundo somente para a API de Eventos de Conversão via API Key.

---

OAuth

Pré-requisitos

Antes de iniciar o processo de autenticação, cheque se você já possui:

• Uma conta do RD Station, se ainda não tiver, crie uma aqui.
• Uma url de callback para receber a primeira credencial da conta.
• Credenciais client_id e client_secret.

📘

O que é uma URL de callback?

Num fluxo de autenticação, o seu aplicativo solicita autorização para ter acesso a uma conta dentro da estrutura do RD Station. Por isso, precisamos de um "endereço de entrega" do seu aplicativo para podermos devolver essa autorização, caso nosso cliente autorize a conexão da sua aplicação com o RD Station. Esse endereço de entrega é a url de callback.

Uma url de callback se parece com isso: <https://nomedoapp.org/auth/callback>

📘

O que são Credenciais?

No fluxo OAuth de autenticação, seu aplicativo possui duas credenciais, que chamamos declient_ide`client_secret. Essas credenciais são utilizadas para gerar tokens de acesso.
Uma vez que um token de acesso tenha sido gerado, ele será utilizado nas trocas de mensagens via API.

Se você ainda não possui essas credenciais, poderá gerá-las acessando a RD Station App Store. É lá que você irá fazer o processo de submissão do seu aplicativo, e após isso suas credenciais serão criadas.

Caso você já possua as credenciais, poderá iniciar o processo de autenticação agora mesmo.

Passo a passo resumido do fluxo de autenticação

Passo 1:

Criar um aplicativo na RD Station App Store

Passo 2:

Substituir os campos da URL abaixo pelos dados que você vai obter do aplicativo. <https://api.rd.services/auth/dialog?client_id={client_id}&redirect_uri={redirect_uri}>

Passo 3:

Clicar no link e realizar login no RD Station Marketing.

Passo 4:

Após login e confirmação de acesso, enviaremos o code para a URL de callback.

Passo 5:

Solicitar o access_token e refresh_token a partir do code gerado, enviando uma requisição para a nossa API.

Passo 6:

Pronto! Agora você já pode enviar dados para a nossa API com o access_token recebido.

Iniciando o processo de autorização

Seu aplicativo deverá direcionar o usuário para a URL de autorização indicada abaixo, substituindo os parâmetros client_id e redirect_uri por suas credenciais. Veja o exemplo:

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

Request Parameters

Você verá a caixa de confirmação da autorização, conforme mostrado a imagem abaixo. Clique no botão para confirmar o acesso.

Feita a confirmação, o RD Station retornará com uma URL de callback, que contém o parâmetro code.
Veja no exemplo:

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

Esse processo só precisa ser feito uma vez \O/

Porém pode-se repetir caso você queira gerar um novo code ou o usuário seja desconectado.

Obs: Se a url de callback possuir query string, o valor deve ser passado em formato encoded.
Exemplo:

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

Obtendo tokens de acesso

Uma vez recebido o parâmetro code, só falta obter o token de acesso. Para isso basta fazer uma requisição para obter o access_token:

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

Request Parameters

Body Params

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

Response Body Parameters

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

Com o access_token gerado, este deverá ser enviado no cabeçalho de cada requisição para a API Pública.

Atualizando um token expirado

Todo access_token é temporário, e tem como prazo de validade o valor definido pelo atributo expires_in em segundos, que é de 86400 segundos (24 Horas).

Um novo access_token é gerado utilizando o refresh_token, exemplo:

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

Request Parameters

Body Params

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

Response Body Parameters

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

Invalid Grant - 401 Unauthorized

Response Headers

_WWW-Authenticate: Bearer realm="https://api.rd.services/

", error="invalidgrant", 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"}'`

Revogando o acesso de um token

O acesso dos clientes com autenticação do tipo OAuth pode ser revogado sempre que necessário. Isso pode ser feito utilizando o access_token ou o refresh_token, por exemplo:

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

Request Headers

Request Parameters

Body Params

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