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. - Um aplicativo para se conectar com os seguintes dados:
-Se ainda não tiver um aplicativo, crie um aqui.
-Uma url de callback para receber a primeira credencial da conta.
-Credenciais client_id e client_secret.
Para criar um aplicativo, basta seguir essa documentação.
Como funciona?
- Seu aplicativo abre uma janela no navegador para o usuário autorizar o aplicativo ter acesso a sua conta RD Station
- O usuário revisa as permissões e autoriza o acesso a conta
- O usuário é redirecionado de volta para o aplicativo e é enviado na URL o parâmetro code
- O aplicativo faz uma requisição para gerar um novo token a partir do
code
Vamos ver na prática!
Para exemplificar, vamos supor que criamos um aplicativo na appstore e possuímos essas credenciais:
| Campo | Valor |
|---|---|
| client_id | 68956445-3421-4a0f-a0dd-3142a97621f4 |
| client_secret | 81f840006c994d71a87d0b4fa6e2f0a2 |
| url_callback | https://www.rdstation.com/contato |
1. Criando URL de autorização
Seu aplicativo deverá direcionar o usuário para a URL de autorização, substituindo os parâmetros client_id e redirect_uri por suas credenciais.
Gerador de URL de autorização
| Campo | Valor | Descrição |
|---|---|---|
| client_id do aplicativo | ||
| redirect_uri do aplicativo | ||
| (Opcional) Você pode utilizar esse parâmetro para repassar alguma informação para a URL de callback |
Utilizando nosso exemplo:
https://api.rd.services/auth/dialog?client_id=68956445-3421-4a0f-a0dd-3142a97621f4&redirect_uri=https://www.rdstation.com/contato>
# Utilizando state
https://api.rd.services/auth/dialog?client_id=68956445-3421-4a0f-a0dd-3142a97621f4&redirect_uri=https://www.rdstation.com/contato&state=ID_CONTA_NO_MEU_APP
2. Usuário autorizando o aplicativo
Você verá a caixa de confirmação da autorização, conforme mostrado a imagem abaixo. Clique no botão para confirmar o acesso.
Clicando em Conectar, o RD Station redirecionará o usuário para a URL de callback com o parâmetro code e com o parâmetro state caso você tenha utilizado ele.
Utilizando nosso exemplo:
https://www.rdstation.com/contato/?code=f12271c9bd1b0eade3ec31f89c87ca60
Se tivessemos utilzado o state, seriamos redirecionado para essa url
https://www.rdstation.com/contato/?code=f12271c9bd1b0eade3ec31f89c87ca60&state=ID_CONTA_NO_MEU_APP
3. Gerar um token a partir do code
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.
O parâmetro
coderecebido como query param na URL de callback é válido por 1 hora, caso esse tempo seja excedido os passos deverão ser refeitos para obter um novocode.
Para isso, basta utilizar a rota Obtendo primeiro token de acesso da nossa API.
Utilizando nosso exemplo:
Com o access_token gerado, este deverá ser enviado no cabeçalho de cada requisição para a API Pública.
| Header | Required |
|---|---|
| Authorization: Bearer access_token | Required on client request |
| Content-Type: application/json | Required on client request |
O 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).
4. Atualizando um token expirado
Após gerar o primeiro token, os demais serão gerados utilizando o refresh_token.
Para isso, basta utilizar a rota Obtendo token de acesso pelo refresh_token da nossa API.
Utilizando nosso exemplo:
5. Revogando o acesso de um token
O acesso dos clientes com autenticação do tipo OAuth pode ser revogado sempre que necessário.
Para isso, basta utilizar a rota Revogando o acesso de um token da nossa API.
Utilizando nosso exemplo:
