Autenticação

Autenticação

A autenticação das APIs é realizada com a informação de um par de tokens no cabeçalho (header) das requisições. O seguinte par de tokens é esperado em cada requisição:

client_id: Identificação de acesso do cliente. Esse token é gerado pela ANBIMA e informado ao cliente. Porém, também o possível o cliente gerar seu próprio client_id aqui no portal do desenvolvedor para validar as chamadas aos recursos utilizando o Swagger.

access_token: armazena as regras de acesso permitidas ao client_id. Esse token pode ser obtido de forma processual, para qualquer ambiente, seguindo um fluxo de autenticação OAuth2(Saiba mais sobre o fluxo OAuth2) – padrão de autenticação amplamente utilizado, o qual permite que sua aplicação não manipule diretamente nomes de usuários e senhas. Empresas como Google, Facebook e Twitter já utilizam esse padrão, provendo o acesso a seus recursos de forma segura a aplicações de terceiros.

Protocolo de Transporte

Todas as informações trafegadas pelas APIs são realizadas através do protocolo HTTPS, que garante um canal é seguro e dispensa a criptografia dos tokens de forma manual. Saiba mais detalhes sobre a utilização do protocolo HTTPS.

OAuth 2

OAuth é um padrão de autenticação amplamente utilizado, que permite que sua aplicação não manipule diretamente nomes de usuários e senhas. Empresas como Google, Facebook e Twitter já utilizam esse padrão para prover o acesso à seus recursos de forma segura à aplicações de terceiros.

Abaixo você confere os passos necessários para conclusão do processo de integração OAuth2:

1. Obtenção do Client ID e Client Secret

Assim que todas questões contratuais estiverem fechadas com a ANBIMA o cliente receberá o client_id e o client_secret para utilização no fluxo de OAuth

2. Obtenção do Access Token

Tendo obtido o client_id e o client_secret, é hora de trocá-los pelo access_token, que permitirá o acesso às APIs da ANBIMA.

Na prática, é necessário realizar a chamada abaixo para nossa API de OAuth:

						
POST
https://api.anbima.com.br/oauth/access-token

HEADER
Content-Type: application/json
Authorization: Basic base64(client_id:client_secret)

REQUEST BODY
{
	"grant_type": "client_credentials"
}
						
					

As informações passadas para o campo Authorization devem ser codificadas em base 64. Assim, para gerar o header Authorization do par client_id = aC2yaac23 e client_secret = 1bhS45TT, por exemplo, deve ser gerada a base64 da string "aC2yaac23:1bhS45TT", que resultará na chave YUMyeWFhYzIzOjFiaFM0NVRU. Desta forma, o header ficaria: ‘Authorization’: ‘Basic YUMyeWFhYzIzOjFiaFM0NVRU’.

Após essa chamada, será obtida a seguinte resposta de API de OAuth 2.0:

						
{
	// O access_token gerado deve ser armazenado para ser utilizado nas chamadas à API
	"access_token": "222rkya88",
	"token_type": "access_token",
	"expires_in": 3600
}
						
					

Na resposta, é indicado o tempo de expiração em segundos para o "access_token". Após sua expiração, o mesmo procedimento indicado deve ser repetido para obtenção de um novo token.

3. Chamadas à API

Agora que o Access Token foi obtido sua aplicação pode finalmente realizar chamadas à API utilizando os endpoints de Sandbox e Produção (o Swagger contendo as chamadas aos recursos de nossas APIs estão disponíveis aqui).

Erros de Autenticação

Alguns erros serão tratados durante a autenticação dos Tokens (client_id e access_token). Abaixo a lista dos erros:

Código Tipo de erro Descrição
401 Token inexistente/errado Se qualquer um dos Tokens passados não existir ou estiver com algum erro (caso tenha sido alterado), será retornado o erro 401 Unauthorized
403 Tokens revogados (inválidos) ou recursos da API indisponíveis para o plano contratado na ANBIMA Se qualquer um dos Tokens tiver sido revogado ele será considerado inválido e será retornado o erro 403 Forbidden. Da mesma forma, caso o recurso acessado não for permitido para o plano contratado, este mesmo erro será retornado

Para os erros de ausência de um dos tokens e/ou token inexistente/errado, medidas podem ser tomadas do lado do desenvolvedor para validar se as informações que estão sendo passadas estão válidas. Para o erro de tokens revogados (inválidos) a única ação cabível será solicitar um novo token.