Este guia foi elaborado para orientar você, passo a passo, no processo de criação de credenciais e certificados para suas aplicações. Através dele, você aprenderá como gerar, armazenar e gerenciar suas credenciais de forma segura e eficiente, garantindo o acesso controlado aos ambientes desejados.

Abordaremos desde a criação inicial da credencial, passando pela geração do certificado, até as melhores práticas para o armazenamento dos dados sensíveis, como o Client ID e Client Secret. Além disso, você encontrará instruções para revogar credenciais e lidar com possíveis erros durante o processo.

a. Na página da aplicação para a qual você quer obter credencial, clique em Credenciais e certificados ou clique no card (b) presente mais abaixo na página.

c. Clique no botão criar credencial para iniciar o fluxo de criação.

Para criar a credencial é muito simples, basta escolher o ambiente para o qual ela será válida e dar um nome.

d. Com a credencial criada, não esqueça de copiar o Client ID e Client Secret em um local seguro. Conforme alertamos em amarelo (d) ela será exibida uma única vez e não iremos armazenar o Client Secret em local algum por segurança.

Criação de certificado

Com a credencial criada, registramos tudo em um card identificando o nome, ambiente, últimos 6 caracteres do Client ID, quem criou e quando. Para gerar o certificado da credencial criada, clique em Gerar certificado (e).

Para geração do certificado, o primeiro passo é gerar o token temporário. Coloque o Client Secret da credencial e clique em Gerar token temporário (f).

Com o token gerado, agora termine de preencher os demais campos de identificação do certificado conforme solicitado e clique em Gerar certificado (g).

Com o certificado criado, faça o download para sua máquina clicando em Baixar certificado (h).

Pronto! Com credencial e certificado criadas fica tudo registrado em um card (i) com o nome do usuário que fez a operação, a data de criação e expiração do certificado. A qualquer momento você pode revogar a credencial clicando em Revogar (j).

Alertamos o usuário quando o certificado está há 30 dias de expirar (j). Nesses casos, é exibido um botão (k) para gerar um novo certificado.

Como renovar o certificado?

A renovação do certificado dinâmico é essencial para garantir a comunicação segura entre sua aplicação e as APIs do Itaú. O certificado dinâmico tem validade de 365 dias, e o processo de renovação deve ser iniciado dentro da janela dos 30 dias finais antes do vencimento.

Cenários de renovação

A renovação do certificado dinâmico pode ocorrer em dois cenários, dependendo da situação do certificado atual:

Certificado ainda válido (dentro da janela de 30 dias)

Quando o certificado ainda não expirou, mas já entrou na janela dos 30 dias finais de validade, existem duas opções para renová-lo. A opção recomendada é gerar um novo certificado completo.

• Coexistência de certificados: Caso o novo certificado seja gerado durante a janela de 30 dias finais do vencimento, ambos os certificados (antigo e novo) serão válidos simultaneamente até que a troca seja concluída e o certificado antigo expire. Isso permite uma transição segura, sem interrupção do serviço.
• Este é o processo recomendado por oferecer maior segurança, uma vez que gera uma nova chave privada e um novo CSR, eliminando riscos associados à reutilização de chaves anteriores.

Resumo do fluxo recomendado:

1. Utilize suas credenciais descriptografadas já existentes (client_id, client_secret, certificado_vigente.crt e chave_privada_vigente.key).

2. Solicite um novo access_token por meio de requisição ao STS Itaú (validade de 5 minutos). Caso expire, solicite novamente.

curl -s -k -X POST "https://sts.itau.com.br/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --cert ./certificado_vigente.crt \
  --key ./chave_privada_vigente.key \
  -d "grant_type=client_credentials&client_id=abc12345-1234-5678-9abc-def012345678&client_secret=99887766-aabb-ccdd-eeff-001122334455"

3. Gere um novo CSR e uma nova chave privada utilizando comandos OpenSSL conforme seu sistema operacional (Windows, Linux ou macOS)

Para isso siga os passos a seguir:

Pré-requisitos

• client_id e token temporario decifrados
• OpenSSL instalado

Comandos para gerar o CSR

Windows

openssl req -new -subj "//CN={{CLIENT_ID}}\OU={{SITE OU APP DO PARCEIRO}}\L={{CIDADE}}\ST={{ESTADO}}\C={{PAIS}}" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

Linux e macOS

openssl req -new -subj "/CN={{CLIENT_ID}}/OU={{SITE OU APP DO PARCEIRO}}/L={{CIDADE}}/ST={{ESTADO}}/C={{PAIS}}" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

Exemplo de como deve ficar o comando a ser executado:

openssl req -new -subj "//CN=56a29ee3-60fe-47f8-95d9-7538b80ccf04\OU=ABC LTDA\L=SAO PAULO\ST=SP\C=BR" -out ARQUIVO_REQUEST_CERTIFICADO.csr -nodes -sha512 -newkey rsa:2048 -keyout ARQUIVO_CHAVE_PRIVADA.key

Parâmetros

Arquivos gerados

Validação (opcional)

openssl req -in ARQUIVO_REQUEST_CERTIFICADO.csr -noout -text

Verifique se o CN (Common Name) é exatamente igual ao client_id. Confira também os campos OU, L, ST e C.

4. Envie o novo CSR para a rota de renovação: POST /seguranca/v2/certificado/renovacao.

Curl exemplo:

curl --request POST \
  --url 'https://sts.itau.com.br/seguranca/v2/certificado/renovacao' \
  --header 'Authorization: Bearer $TOKEN GERADO NO PROCESSO ANTERIOR' \
  --header 'Content-Type: text/plain' \
  --header 'x-itau-correlationID: 1fcfd2bf-7476-49a0-94cb-aa16fb33ff9f' \
  --cert ./certificado.crt \
  --key ./chave_privada.key \
  --data '-----BEGIN CERTIFICATE REQUEST-----
(Cole aqui o conteúdo do novo arquivo .csr)
-----END CERTIFICATE REQUEST-----'

5. O retorno da API trará o novo certificado emitido pelo Itaú no formato .crt.

6. Salve o novo certificado e atualize as referências em sua aplicação.

Vantagens desta opção:

• Maior segurança com chaves criptográficas totalmente novas.
• Coexistência dos dois certificados durante a transição, evitando indisponibilidade.
• Conformidade com as melhores práticas de segurança.

Certificado expirado

Se o certificado dinâmico expirou, ou seja, decorreu o prazo de validade de 365 dias do seu arquivo .CRT, é necessário gerar um novo certificado dinâmico, siga o fluxo a seguir:

1. Utilize suas credenciais existentes geradas anteriormente;
2. Siga o fluxo de criação de Criação de certificado para gerar um novo .crt.

Como fazer a primeira chamada a uma API?

Depois de criar sua credencial e gerar o certificado, você já tem tudo o que precisa para consumir as APIs do Itaú. Este guia mostra como fazer isso usando curl na linha de comando.

Pré-requisitos

Ao final da jornada de criação de credencial e certificado no DevPortal, você terá os seguintes dados e arquivos:

Passo 1 — Gerar o access token

Antes de chamar qualquer API, você precisa obter um access token. Esse token é a autorização que permite sua aplicação acessar os serviços do Itaú.

A chamada utiliza mTLS (mutual TLS), ou seja, tanto o servidor quanto a sua aplicação se autenticam mutuamente por meio do certificado.

Comando curl

curl -s -k -X POST "https://sts.itau.com.br/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --cert /caminho/para/seu-certificado.crt \
  --key /caminho/para/sua-chave-privada.key \
  -d "grant_type=client_credentials&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"

O que cada parâmetro significa

Exemplo com valores preenchidos

curl -s -k -X POST "https://sts.itau.com.br/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --cert ./certificado.crt \
  --key ./chave_privada.key \
  -d "grant_type=client_credentials&client_id=abc12345-1234-5678-9abc-def012345678&client_secret=99887766-aabb-ccdd-eeff-001122334455"

Resposta esperada

Se tudo estiver correto, você receberá uma resposta como esta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 300
}

Guarde o valor do campo access_token, ele será usado no próximo passo.

Passo 2 — Chamar a API

Com o access token em mãos, você já pode fazer a chamada à API desejada. A conexão continua usando mTLS, então o certificado e a chave privada também são necessários nesta etapa.

Comando curl

curl -s -k -X GET "https://api.itau.com.br/{api}/{versao}/{recurso}" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --cert /caminho/para/seu-certificado.crt \
  --key /caminho/para/sua-chave-privada.key

O que substituir

Exemplo de chamada

curl -s -k -X GET "https://api.itau.com.br/pix/v2/cob" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
  -H "Content-Type: application/json" \
  --cert ./certificado.crt \
  --key ./chave_privada.key

Se a autenticação e o endpoint estiverem corretos, a API retornará uma resposta de sucesso (HTTP 200).