Este glossário reúne os principais conceitos e termos que você encontra ao se conectar às APIs do Itaú — de certificado e chaves a tokens e siglas de protocolo. Use como referência rápida sempre que precisar.
Conceitos principais
O que é o certificado dinâmico (CSR)?
O Certificate Signing Request (CSR) é um certificado não assinado, usado apenas no ambiente de produção. Ele é gerado pelo responsável técnico e contém os dados da empresa solicitante e a sua chave pública.
Com o CSR, ao solicitar um certificado ao Itaú, você identifica a sua aplicação e recebe um certificado de uso único e exclusivo.
O CSR é o arquivo que contém a chave pública do certificado e as demais informações de identificação. Você usa ele para pedir ao STS Itaú a assinatura do certificado.
O formato segue este padrão:
-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----
A segurança do processo é baseada no conceito de chave assimétrica (ou chave pública).
Importante
- Para renovar ou gerar o certificado dentro da validade de 365 dias: use o arquivo .CSR gerado antes e o token temporário gerado pela sua aplicação, válido por 5 minutos.
- Depois dos 365 dias de validade: solicite um novo token temporário ao seu ponto focal do Itaú. Nesse cenário, o token vale 7 dias corridos.
O que é a chave pública?
A chave pública é um valor gerado a partir de operações matemáticas com a chave privada. Como o nome sugere, pode ser de conhecimento público e não precisa ser guardada de forma confidencial. O valor dela fica embutido no próprio certificado.
O que é a chave privada?
A chave privada é um valor altamente sensível, então guarde com segurança. Ela é usada para comprovar que o certificado está em uso pelo dono no processo de mutual TLS (mTLS).
O formato segue este padrão:
-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----
O que é SSL?
O SSL (Secure Sockets Layer) garante segurança na comunicação entre cliente e servidor, preservando a integridade e a veracidade do conteúdo que trafega na rede, com autenticação das partes envolvidas. A versão recomendada pelo banco é a 1.1.1c ou superior.
O que são credenciais?
As credenciais são o conjunto client_id + client_secret.
O que é o token temporário?
O token é um valor obtido no STS Itaú que representa a autenticação da credencial. Ele é obrigatório para consumir as APIs do Itaú, junto com o certificado.
Como faço para obter um token temporário?
Depende da etapa da jornada em que você está: onboarding ou consumo.
- Etapa de onboarding: é quando você está começando o contato com o Itaú. Você recebe um token temporário por e-mail, válido por 7 dias corridos, só para emitir as suas credenciais e o certificado. Depois desse prazo, o token é invalidado. Faça o recebimento das credenciais e a emissão do certificado dentro do prazo, contado a partir da emissão do token.
- Etapa de consumo: é quando você já tem as credenciais e o certificado emitidos pelo STS Itaú. A emissão do token é simples e você faz por uma requisição ao STS Itaú.
Importante (onboarding): o token vale 7 dias para iniciar o fluxo de geração do certificado. Se não usar nesse período, solicite de novo e aguarde o tempo de resposta, de 1 dia útil.
Importante (consumo): o token emitido pelo STS Itaú dura 5 minutos e precisa ser usado nesse período. Renove sempre que estiver perto de expirar.
Glossário de termos (A–Z)
Definições rápidas dos termos mais usados na integração com as APIs do Itaú.
| Termo | Definição |
|---|---|
| access token | É um JWT que contém informações de uma autenticação. Ele é validado a cada chamada de API para identificar quem se autenticou e se tem permissão para o recurso solicitado. |
| arquivo .CRT (Certificate File) | No mesmo formato do .KEY e do .CSR, é o certificado que, no nosso contexto, contém as informações e assinaturas das duas partes envolvidas: consumidor da API e Itaú. |
| arquivo .CSR (Certificate Signing Request) | No mesmo formato de um .KEY, contém as informações que precisam constar em um certificado gerado por uma CA (Certificate Authority, ou autoridade de certificação) e a assinatura do solicitante, feita com a sua chave privada. |
| arquivo .KEY | Assim como no JWK, é uma chave criptográfica primária em um bloco de texto codificado — mas em formato de arquivo e com codificação diferente de um JWT. Ex.: arquivo.key. |
| bearer token | É um dos tipos de access token mais comuns e usado nas nossas APIs. |
client_credentials |
Tipo de autorização (grant) que obtém um access token fora do contexto de um usuário (pessoa). |
client_id |
Identificador único e público de uma aplicação no fluxo OAuth 2.0. |
client_secret |
Segredo conhecido só pela aplicação e pelo servidor de autorização ao qual pertence um client_id. |
JWKS_URI |
Endereço de internet onde é possível localizar um JWKS para validar a autenticidade de um private_key_jwt. |
| JWK (JSON Web Key) | Estrutura JSON que representa uma chave criptográfica, normalmente a primária (private_key). |
| JWKS (JSON Web Key Set) | Conjunto de chaves (JWK) que contém as chaves públicas (public_key) usadas para verificar qualquer JWT emitido e assinado por uma chave privada (private_key). |
| JWT (JSON Web Token) | Método compacto e autocontido de transmitir dados no formato JSON. Referência: jwt.io/introduction e jwt.io. |
| mTLS (Mutual Transport Layer Security) | No nosso contexto, é um método de segurança baseado em certificados gerados por uma chave privada e uma pública (ou primária e secundária), das duas partes (mútua). Também conhecido como two-way authentication. |
private_key |
Chave criptográfica (primária) usada para codificar mensagens destinadas a um destinatário específico. As mensagens criptografadas só podem ser decifradas por uma segunda chave, a public key. |
private_key_jwt |
JWT assinado por uma chave privada (private_key). |
| public key | Chave criptográfica (pública/secundária) usada para decodificar mensagens destinadas a um destinatário específico. |
| STS (Security Token Service) | Servidor de autorização responsável por gerenciar os tokens de acesso e autorizar as requisições às APIs. |
| token temporário de ativação | No contexto do Itaú, é um primeiro access token, usado para ativar o fluxo de mTLS do nosso processo de autenticação. |
| URI (Uniform Resource Identifier) | Identificador uniforme de recurso. No nosso contexto, especifica um endereço único de internet de um recurso para uma determinada função. |