Objetivo
O conteúdo desta documentação é indicado para times de tecnologia, que visam se autenticar no ambiente produtivo para utilizar nossas soluções. Aqui você encontra um compilado introdutório sobre os procedimentos para realizar a autenticação em produção, além de um glossário com termos relevantes para seu conhecimento.
Arquitetura de autenticação
O modelo de nossas APIs é RESTful, seguem as regras definidas pela arquitetura REST - (Representational State Transfer) (referência: W3C), e utilizam o JSON como formato de troca de dados (referência: JSON.org).
Nossas APIs são compatíveis com o protocolo OAuth 2.0, contemplando especialmente o fluxo client_credentials e mTLS para autorizar acesso a dados e transações, baseado em tokens de acesso no qual utilizamos fluxos específicos para a situação server-to-server.
Porém, é importante destacar que as APIs de Sandbox não seguem a especificação do OAuth 2.0 e não tem mTLS, por outro lado, já as APIs de Produção seguem a especificação do OAuth 2.0 e tem mTLS. Se faz necessário saber também que, os access_tokens gerados para o fluxo do Sandbox só podem chamar a URL de Sandbox.
Recomendamos fortemente que, a etapa de testes em Sandbox seja realizada antes das chamadas para as APIs produtivas, já que, é neste momento que você pode testar vários cenários para entender o processo de implantação do certificado e facilitar sua aplicação no ambiente produtivo.
Importante: O certificado é válido por 365 dias e o access_token por 5 minutos, portanto, atente-se em enviar o certificado dentro do prazo vigente, tanto para gerar o token quanto para chamar a API.
Credenciais produtivas
Para conseguir acessar nossas APIs no ambiente produtivo você precisa gerar o Certificado Dinâmico, para isso, é necessário ter em mãos suas credenciais produtivas, ou seja, a chave pública, chave privada e o token temporário, específicas para o ambiente de produção.
Confira abaixo mais detalhes para solicitar suas respectivas credenciais:
Credenciais para Cobranças e uso externo
As Credenciais para Cobranças e uso externo devem ser solicitadas através dos canais de suporte combinados com o seu ponto focal no Itaú ou API Owner. Você receberá as credenciais por meio de um e-mail com as informações criptografadas, pois elas são confidenciais, e é de sua responsabilidade armazená-las em local seguro, caso contrário elas serão revogadas pelo Itaú.
Credenciais para PIX pagamentos, PIX recebimentos e Bolecode
Já as Credenciais para PIX pagamentos, PIX recebimentos e Bolecode, não são criptografadas, portanto, basta sinalizar ao time OfficerCash, responsável por acionar o time de Backoffice, para gerar uma solicitação e lhe enviar suas credenciais (client_id e token temporário) via e-mail.
Token temporário
Deve ser solicitado através dos canais de suporte combinados com o seu ponto focal no Itaú ou API Owner. O token temporário será enviado para você por e-mail em até 1 dia útil depois da solicitação e terá validade de 7 dias corridos.
URL Produção
base token URL produção: sts.itau.com.br
Lembre-se: Consulte na documentação de cada API qual é o endereço de produção exato para utilizar a URL correta, pois há variação entre elas.
Fluxos de autenticação do Itaú
O Itaú oferece dois fluxos de autenticação para acesso ao ambiente produtivo e você pode escolher conforme sua necessidade.
Confira abaixo os fluxos disponíveis:
1 - Client credentials e mTLS - É o fluxo em que após receber seu client_id Itaú produtivo e token de ativação temporário você estará apto a gerar um certificado de autenticação válido e assinado tanto por você quanto pelo Itaú e, fazendo o envio dessas informações em cada requisição de API, você poderá consumir nossas APIs em Produção.
Confira como realizar o procedimento do fluxo mTLS
- Solicite o client_id + token temporário com o seu ponto focal ou API Owner do Itaú;
- Após receber as credenciais, crie e assine o certificado de autenticação e envie para o Itaú;
- Em seguida você precisará gerar seu access_token e automatizar o processo de criação de um novo access_token a cada 5 minutos, a qual a validade do token é de 300 segundos;
- Finalize seu desenvolvimento enviando o certificado assinado + access_token em cada requisição de API para que as chamadas possam ser concluídas.
Dica: Para saber mais sobre como receber suas credenciais do Certificado de Autenticação, também conhecido como Certificado Dinâmico, consulte nossa documentação.
Exemplos de obtenção do access_token