iCarros OAuth API
API para autenticação para uso dos serviços iCarros

Primeiros passos

Todas as aplicações seguem um padrão básico ao acessar uma API do iCarros usando OAuth 2.0. Em um nível alto, você segue quatro passos:

  1. Obter suas credenciais do OAuth 2.0
  2. Obter um token de acesso
  3. Consultar um serviço da API
  4. Renovar o token de acesso

Obter suas credenciais do OAuth 2.0

Entre em contato com a nossa central de atendimento para obter as suas credenciais de acesso tais como o seu client id e o seu client secret.

Obter um token de acesso

Antes de seu aplicativo poder acessar dados privados usando uma API do iCarros, ele deve obter um token de acesso que concede acesso à API em nome de um usuário do iCarros. Um token de acesso único pode conceder diferentes graus de acesso a múltiplas APIs. Um parâmetro variável chamado escopo controla o conjunto de permissões que um token de acesso irá possuir. Durante o pedido de token de acesso, o aplicativo envia um ou mais valores no parâmetro escopo (scope)

Alguns pedidos exigem uma etapa de autenticação em que o usuário faz login com a sua conta do iCarros. Após o login, o usuário é perguntado se está disposto a conceder as permissões que o aplicativo está solicitando (parâmetro escopo). Este processo é chamado o consentimento do usuário. É um quesito de segurança pois o aplicativo que fará a integração através de um usuário não precisa conhecer a senha deste usuário.

Se o usuário concede a permissão, o Servidor de Autorização do iCarros envia ao seu aplicativo um código de autorização que seu aplicativo deverá usar para obter um token de acesso. O Cliente precisa implementar um serviço ou um aplicativo que receba essas informações que o iCarros irá fornecer (url de callback) que receberá o código de acesso e providenciará sua troca por um token de acesso. Se o usuário não conceder a permissão, a url de callback não receberá o access_code, e sim uma indicação de erro.

Juntamente com o token de acesso (access_token) o servidor de autorização enviará um token de renovação da sessão (refresh_token), além de outros dados relevantes como o tempo de validade do token (expires_in), e um token de identificação (id_token). O retorno é em formato JSON.

Consultar um serviço da API

Depois que uma aplicação obtém um token de acesso, ela envia o token em um header "Authorization" nas requisições que fizer a nossas APIs.

Os tokens de acesso só são válidos para o conjunto de operações e recursos descritos no âmbito do pedido de token.

Renovar o token de acesso

Os tokens de acesso têm vida útil limitada - normalmente não superior à 1 hora . Se tiver necessidade de acesso a API iCarros para além do tempo de vida de um único token de acesso, pode obter um novo token utilizando o token de renovação (refresh_token).

Tipos de Autorização

Resource Owner Password Credentials ( Direct Access Grants)

Ideal para: Montadoras e demais parceiros que possuem senha própria no iCarros.

Nesse tipo de solicitação não existe nenhuma interação do usuário e o servidor de autenticação não retorna o código de autorização para ser trocado por um token de acesso. A aplicação solicita e recebe diretamente o token de acesso e o token de atualização sendo necessário enviar na solicitação o usuário e a senha de acesso.

A aplicação deve armazenar o token de atualização para uso futuro e utilizar o token de acesso para acessar às API do iCarros. Uma vez que o token de acesso expire, o aplicativo usa o token de atualização para obter um novo token de acesso.

Esse método deve ser utilizado apenas por aplicações que possuem senhas do iCarros, e não por aplicações que tratam de dados de terceiros (ex: integrador que atualiza o estoque de uma loja, e para isso armazena a senha desta loja). Por esse motivo, este método de autenticação pode estar bloqueado para a maioria dos clientes e não funcionar.

Solicitando o token de acesso

https://accounts.icarros.com/auth/realms/icarros/protocol/openid-connect/token

Campo Descrição
username O nome do usuário.
password A senha do usuário.
client_id O código do cliente fornecido pelo iCarros.
client_secret O código secreto fornecido pelo iCarros.
response_type Conforme definido na especificação do OAuth 2.0, este campo deve conter o valor “token”.
grant_type Conforme definido na especificação do OAuth 2.0, este campo deve conter o valor “password”.

A solicitação deve ser parecida com a seguinte:

POST /auth/realms/icarros/protocol/openid-connect/token HTTP/1.1
Host: accounts.icarros.com
Content-Type: application/x-www-form-urlencoded

username=usuario&
password=senha&
client_id={client_id}&
client_secret={client_secret}&
response_type=token&
grant_type=password

Uma resposta bem sucedida é retornado como uma matriz JSON, semelhante a que segue:

{"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIwNTVmZWExMC1iYzg3LTQ4YzYtOWMzZC1kMTM3YmVhNjRhMTgiLCJleHAiOjE0NzE2MjExMDEsIm5iZiI6MCwiaWF0IjoxNDcxNjE3NTAxLCJpc3MiOiJodHRwczovL2FjY291bnRzLmljYXJyb3MuY29tL2F1dGgvcmVhbG1zL2ljYXJyb3MiLCJhdWQiOiJ2b2xrc3dhZ2VuIiwic3ViIjoiOTZmNTY5OGItOGYwMC00NTE4LWFlOTEtMmVlY2ViY2ZhMzY1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidm9sa3N3YWdlbiIsInNlc3Npb25fc3RhdGUiOiIyZTZkNmRjMi02MmJhLTQ1ZmItOGEwZS0yNTNjMjE0NzVlNjkiLCJjbGllbnRfc2Vzc2lvbiI6ImJkMDU4YWQwLTEwYzUtNDdiMy1iMWE0LTk1OTNiY2RmYmE2OCIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImljYXJyb3Mtd2ViYXBwIjp7InJvbGVzIjpbInVzdWFyaW9zaXRlIiwiZ3J1cG9yZWdpb25hbCJdfX0sIm5hbWUiOiJHdWlsaGVybWUgQnJhZ2EiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJndWlsaGVybWUuYnJhZ2FAaWNhcnJvcy5jb20uYnIiLCJnaXZlbl9uYW1lIjoiR3VpbGhlcm1lIiwiZmFtaWx5X25hbWUiOiJCcmFnYSIsImVtYWlsIjoiZ3VpbGhlcm1lLmJyYWdhQGljYXJyb3MuY29tLmJyIn0.ZVyvOIMndQtN417gI_a2PhhwvZG4Wy1M_BHK4gvk26PTtobROcrHx9JgsCmg6FQmZ6hlMf9cai1C9wdbIXa2qsrhvpfadfiA0QwZyyCoMJmL9WQrordsPgD7HUrZQlwd87O5P3Slfmdwgx8KHsmcRWUq-USiPCR5vGTlIguuA24","expires_in":3600,"refresh_expires_in":0,"refresh_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI3ODc3ZTM5Mi1jNzRlLTRiMjItYjQ3Yi04MDMxYWJlMzkzZjAiLCJleHAiOjAsIm5iZiI6MCwiaWF0IjoxNDcxNjE3NTAxLCJpc3MiOiJodHRwczovL2FjY291bnRzLmljYXJyb3MuY29tL2F1dGgvcmVhbG1zL2ljYXJyb3MiLCJhdWQiOiJ2b2xrc3dhZ2VuIiwic3ViIjoiOTZmNTY5OGItOGYwMC00NTE4LWFlOTEtMmVlY2ViY2ZhMzY1IiwidHlwIjoiT2ZmbGluZSIsImF6cCI6InZvbGtzd2FnZW4iLCJzZXNzaW9uX3N0YXRlIjoiMmU2ZDZkYzItNjJiYS00NWZiLThhMGUtMjUzYzIxNDc1ZTY5IiwiY2xpZW50X3Nlc3Npb24iOiJiZDA1OGFkMC0xMGM1LTQ3YjMtYjFhNC05NTkzYmNkZmJhNjgiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiXX0sInJlc291cmNlX2FjY2VzcyI6eyJpY2Fycm9zLXdlYmFwcCI6eyJyb2xlcyI6WyJ1c3Vhcmlvc2l0ZSIsImdydXBvcmVnaW9uYWwiXX19fQ.TPO9c_jFB0GOr2tzSHOuIisBJDwUQP3IQVQWoatyGqiyu9fqdG4iz6aaLr8Lb8QLG-eaPdOf_XfGXrXEMOui61jv0jGtObmC8EFDwkXa5CnH6Pz6RfurrlT2Vgb_S2cuPuOsh2iemoOYAxcdPcNWwguEy-FetIAHFL9pdoC8tNY","token_type":"bearer","id_token":"eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJlNjEyNzkyYy00YjM0LTRiYWQtOWM4Yy0yNWZhZDFiMmNlMzMiLCJleHAiOjE0NzE2MjExMDEsIm5iZiI6MCwiaWF0IjoxNDcxNjE3NTAxLCJpc3MiOiJodHRwczovL2FjY291bnRzLmljYXJyb3MuY29tL2F1dGgvcmVhbG1zL2ljYXJyb3MiLCJhdWQiOiJ2b2xrc3dhZ2VuIiwic3ViIjoiOTZmNTY5OGItOGYwMC00NTE4LWFlOTEtMmVlY2ViY2ZhMzY1IiwidHlwIjoiSUQiLCJhenAiOiJ2b2xrc3dhZ2VuIiwic2Vzc2lvbl9zdGF0ZSI6IjJlNmQ2ZGMyLTYyYmEtNDVmYi04YTBlLTI1M2MyMTQ3NWU2OSIsIm5hbWUiOiJHdWlsaGVybWUgQnJhZ2EiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJndWlsaGVybWUuYnJhZ2FAaWNhcnJvcy5jb20uYnIiLCJnaXZlbl9uYW1lIjoiR3VpbGhlcm1lIiwiZmFtaWx5X25hbWUiOiJCcmFnYSIsImVtYWlsIjoiZ3VpbGhlcm1lLmJyYWdhQGljYXJyb3MuY29tLmJyIn0.g6na9ZVfaXv_kRawa42UE-V76GiBjtJWMuJMuCgP2QoeZ7JTIjUDl9uuMTHD9RYb3kymb418-_MR_PZ6lTl-UOXuGmgCsb8oyScINE3_uEjwdWIR0r_wvGifP8EAz34UzLb2VistqQanXDFA_iDS2jsr_wUlx1K8GZTNtIdahxU","not-before-policy":1412634388,"session_state":"2e6d6dc2-62ba-45fb-8a0e-253c21475e69"}

Consultando uma API

Com o token de acesso, efetue as consultas as APIs iCarros incluindo o token no campo Authorization, no header da requisição, conforme exemplo abaixo.

GET /rest/dealerservice/dealer HTTP/1.1
Authorization: Bearer
eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIwNTVmZWExMC1iYzg3LTQ4YzYtOWMzZC1kMTM3YmVhNjRhMTgiLCJleHAiOjE0NzE2MjExMDEsIm5iZiI6MCwiaWF0IjoxNDcxNjE3NTAxLCJpc3MiOiJodHRwczovL2FjY291bnRzLmljYXJyb3MuY29tL2F1dGgvcmVhbG1zL2ljYXJyb3MiLCJhdWQiOiJ2b2xrc3dhZ2VuIiwic3ViIjoiOTZmNTY5OGItOGYwMC00NTE4LWFlOTEtMmVlY2ViY2ZhMzY1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidm9sa3N3YWdlbiIsInNlc3Npb25fc3RhdGUiOiIyZTZkNmRjMi02MmJhLTQ1ZmItOGEwZS0yNTNjMjE0NzVlNjkiLCJjbGllbnRfc2Vzc2lvbiI6ImJkMDU4YWQwLTEwYzUtNDdiMy1iMWE0LTk1OTNiY2RmYmE2OCIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImljYXJyb3Mtd2ViYXBwIjp7InJvbGVzIjpbInVzdWFyaW9zaXRlIiwiZ3J1cG9yZWdpb25hbCJdfX0sIm5hbWUiOiJHdWlsaGVybWUgQnJhZ2EiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJndWlsaGVybWUuYnJhZ2FAaWNhcnJvcy5jb20uYnIiLCJnaXZlbl9uYW1lIjoiR3VpbGhlcm1lIiwiZmFtaWx5X25hbWUiOiJCcmFnYSIsImVtYWlsIjoiZ3VpbGhlcm1lLmJyYWdhQGljYXJyb3MuY29tLmJyIn0.ZVyvOIMndQtN417gI_a2PhhwvZG4Wy1M_BHK4gvk26PTtobROcrHx9JgsCmg6FQmZ6hlMf9cai1C9wdbIXa2qsrhvpfadfiA0QwZyyCoMJmL9WQrordsPgD7HUrZQlwd87O5P3Slfmdwgx8KHsmcRWUq-USiPCR5vGTlIguuA24
Host: paginasegura.icarros.com.br

Solicitando a atualização do token

https://accounts.icarros.com/auth/realms/icarros/protocol/openid-connect/token

Campo Descrição
refresh_token O refresh token retornado na solicitação do token.
client_id O código do cliente fornecido pelo iCarros.
client_secret O código secreto fornecido pelo iCarros.
grant_type Conforme definido na especificação do OAuth 2.0, este campo deve conter o valor “refresh_token”.

A solicitação deve ser parecida com a seguinte:

POST /auth/realms/icarros/protocol/openid-connect/auth HTTP/1.1
Host: accounts.icarros.com
Content-Type: application/x-www-form-urlencoded
refresh_token=eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI3ODc3ZTM5Mi1jNzRlLTRiMjItYjQ3Yi04MDMxYWJlMzkzZjAiLCJleHAiOjAsIm5iZiI6MCwiaWF0IjoxNDcxNjE3NTAxLCJpc3MiOiJodHRwczovL2FjY291bnRzLmljYXJyb3MuY29tL2F1dGgvcmVhbG1zL2ljYXJyb3MiLCJhdWQiOiJ2b2xrc3dhZ2VuIiwic3ViIjoiOTZmNTY5OGItOGYwMC00NTE4LWFlOTEtMmVlY2ViY2ZhMzY1IiwidHlwIjoiT2ZmbGluZSIsImF6cCI6InZvbGtzd2FnZW4iLCJzZXNzaW9uX3N0YXRlIjoiMmU2ZDZkYzItNjJiYS00NWZiLThhMGUtMjUzYzIxNDc1ZTY5IiwiY2xpZW50X3Nlc3Npb24iOiJiZDA1OGFkMC0xMGM1LTQ3YjMtYjFhNC05NTkzYmNkZmJhNjgiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiXX0sInJlc291cmNlX2FjY2VzcyI6eyJpY2Fycm9zLXdlYmFwcCI6eyJyb2xlcyI6WyJ1c3Vhcmlvc2l0ZSIsImdydXBvcmVnaW9uYWwiXX19fQ.TPO9c_jFB0GOr2tzSHOuIisBJDwUQP3IQVQWoatyGqiyu9fqdG4iz6aaLr8Lb8QLG-eaPdOf_XfGXrXEMOui61jv0jGtObmC8EFDwkXa5CnH6Pz6RfurrlT2Vgb_S2cuPuOsh2iemoOYAxcdPcNWwguEy-FetIAHFL9pdoC8tNYb&
client_id={client_id}&
client_secret={client_secret}&
redirect_uri=http://localhost:80/OAuth2ClientSample/authorizationCallback&
grant_type=refresh_token

Expiração do Token

Você deve escrever seu código para antecipar a possibilidade de que um token concedido pode não funcionar mais. Um token pode parar de trabalhar por um destes motivos:

  • O usuário revogou o acesso.
  • O token não for utilizando por mais seis meses.
  • O usuário mudou suas senhas.
  • A conta de usuário tenha ultrapassado um determinado número de solicitações de token (nesse caso o token mais antigo irá expirar).