O que você irá aprender com esse artigo?
- Tipos de autenticação
- Diferenças entre os tokens
- Criando suas chaves de API (API Tokens) via painel
- Como criar os tokens via API
- Como utilizar o live_token e o test_token nas chamadas API
- Assinatura de Requisições (RSA)
Tipos de autenticação
A autenticação na iugu é feita através da utilização de uma chave de API. Esta chave serve para que o sistema identifique a sua conta e conceda permissões para que o sistema se comunique com a iugu em nome da conta em questão.
Há três maneiras de se autenticar, a mais recomendada, utilizando HTTP Basic Auth. A segunda maneira é utilizando a autenticação Bearer Authentication. A outra maneira, é enviar o API Token num parâmetro de nome api_token.
Diferença entre os tokens
Na iugu existem 3 tipos de tokens: live_token, test_token e user_token.
O live token é a autenticação que deve ser usada no ambiente de produção, ou seja, quando as requisições são reais. Em contrapartida, o test_token é para o ambiente de teste, quando as transações são apenas simulações.
O user_token é uma autenticação criada automaticamente juntamente com um usuário padrão, assim que a conta é criada. Ele é utilizado em algumas chamadas da API, que são: Atualizar subconta, Enviar verificação de subconta, Criar convite de usuário, Cancelar convite de usuário, Reenviar convite, Buscar convite, Listar convites, Criar API Token, Remover API Token e Listar API Tokens.
Quando a subconta é criada via API, esses 3 tokens são retornados na chamada de criação da conta. Quando a subconta é criada pelo painel, é necessário realizar uma consulta na API para acessar o user_token. O live_token e test_token podem ser criados via painel, mas o user_token não pode ser gerado de forma manual. Isso significa que se a subconta for criada via painel é necessário que a conta mestre consulte a Listar API de Token das subcontas para conseguir acessar o user_token.
Toggle de Produção/Teste no painel
Este toggle (botão de alteração de ambiente) não altera a comunicação da API e sim, a visão e ações executadas exclusivamente através do painel.
Criando suas chaves de API (API Tokens) via painel
Trate suas chaves de API como senhas
Não inclua sua chave de API publicamente em nenhum lugar do seu site ou javascript. Lembre-se que esta chave dá acesso total ao seus dados na iugu.
Dica de segurança
Recomendamos que você atualize sua chave de API a cada 30 dias - é importante que você mantenha sua chave atualizada evitando que ela seja usada no caso de vazamento de suas informações.
Não se esqueça sua chave de API funciona como uma senha, é ela que libera suas transações de forma automática e autenticada.
Para adicionar uma chave de API, acesse o endereço https://app.iugu.com e siga o tutorial abaixo

Como criar os tokens via API
Como citado anteriormente, o user_token não pode ser gerado manualmente. É possível consultá-lo realizando um GET via API da seguinte forma:
Modelo de request
curl --location --request GET 'https://api.iugu.com/v1/retrieve_subaccounts_api_token' \
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Basic {{apitoken in base64}}'
--header 'Cookie: __cfruid=4ee94e4ee8b72f60ed03623bd362535f80b6646a-1645193529'
Essa consulta retorna o id da subconta, o live_token, test_token e o user_token, a autenticação dessa chamada é realizada com o live_token da conta Mestre. Caso seja necessário, é possível realizar a criação do live_token e do test_token via API da seguinte forma:
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/{{subconta_id}}/api_tokens' \
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Basic {{apitoken in base64}}'
--header 'Cookie: __cfruid=4ee94e4ee8b72f60ed03623bd362535f80b6646a-1645193529' \
--data-raw '{
"api_type": "TEST",
"description": "Meu token"
}'
Basicamente, essa chamada é um POST na API de Criar API Token onde deve ser informado o id da subconta, se o token a ser gerado é de teste ("api_type": "TEST") ou de produção ("api_type": "LIVE") e a requisição deve ser autenticada com o user_token dessa subconta.
Como utilizar o live_token e o test_token nas chamadas API
HTTP Basic Auth
Para gerar o header de autenticação HTTP Basic da request, deve-se seguir os seguintes passos:
-
Ter a chave API, seja de teste ou de Produção
-
Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo= -
No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada
Exemplo: --header 'Authorization: Basic NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=
Modelo de request
curl --location --request GET 'https://api.iugu.com/v1/customers'
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Basic {apitoken in base64}'
--header 'Cookie: __cfruid=df598e45cd90947e522e12ec895a84f7059cacbc-1627922464'
--data-raw ''
Parâmetro api_token
As requests permitem o envio de um parâmetro chamado api_token, onde pode ser enviado o API Token gerado anteriormente em vez de utilizar o HTTP Basic Auth.
HTTP Basic Auth
Você pode aprender mais sobre HTTP Basic Auth em https://en.wikipedia.org/wiki/Basic_access_authentication
Bearer Authentication
Há a possibilidade também de utilizar a autenticação Bearer.
Para gerar o header de autenticação HTTP Bearer, deve-se seguir os seguintes passos:
-
Ter a chave API, seja de teste ou de Produção
-
Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo= -
No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada
Exemplo: --header 'Authorization: Bearer NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=
Modelo de Request
curl --location --request GET 'https://api.iugu.com/v1/customers' \
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'Authorization: Basic {apitoken in base64}'
--header 'Cookie: __cfruid= 95dfe99ff2d3d94d649675cf8cb7491b4bda25b7-1641564409' \
--data-raw ''
Bearer Authentication
Você pode aprender mais sobre Bearer Authentication em
https://learning.postman.com/docs/sending-requests/authorization/#bearer-token
Boas práticas
Como boa prática, é interessante não misturar o que são de fato parâmetros da request da autenticação da mesma. Portanto, recomendamos a utilização de HTTP Basic Auth ou Bearer Authentication.
Assinatura de Requisições (RSA)
Introdução
A assinatura de requisições, tem como objetivo tornar as requisições que são enviadas para a iugu, mais seguras, através da tecnologia RSA.
Este tipo de criptografia tem 3 elementos
- Chave pública (todos podem ver);
- Chave privada (esta chave deve ficar gravada em segurança em seu servidor);
- Mensagem (payload) assinada (criptografada) pela chave privada;
Atenção
Visando aumentar os níveis de segurança de sua conta e garantir que seu negócio esteja sempre protegido, a tecnologia RSA será mandatória para ações de envio de dinheiro para terceiros (TED e PIX).
Assinando requisição na iugu
Libs disponíveis!
Como alternativa para o fluxo abaixo, também disponibilizamos algumas Libs (nas principais linguagens de desenvolvimento da atualidade) para facilitar o processo de Assinatura Digital, Validação de Assinatura, e Requisição de Transferência. Veja abaixo:
Biblioteca RSA
O processo de assinatura de requisição, funciona da seguinte forma:
Através do painel da iugu (Alia), crie uma nova chave API ApiToken
e informe no formulário de criação a chave Pública public_key
Exemplo de chave Pública com extensão .pem
(note que inicia com ----BEGIN PUBLIC KEY----- e termina com ----END PUBLIC KEY----)

Com a chave privada assina o body da requisição usando criptografia SHA256
.
É importante assinar o body de forma raw, crua, sem nenhum tratamento ou parse. O payload que foi assinado é o mesmo que deve ir na requisição.
A assinatura obtida, será preciso criptografar embase64
e adicionar a requisição no campo.
O restante não muda: o body precisa conter o ApiToken e cada campo necessário para dada requisição, sem necessidade de nenhum processo diferente do que já ocorre normalmente.
Validando a assinatura pela iugu
Abaixo segue os passos que realizamos para validar se a assinatura está realizada corretamente:
- Buscar a chave pública procurando pela
ApiToken
que recebemos no body da requisição (se oApiToken
não possuirpublic_key
, retornamos um erro avisando que a chave não foi encontrada).- Decodificamos a assinatura de
base64
para o formato original (SHA256
).- Com a chave pública em nosso banco e com a assinatura decodificada, verificamos se a chave pública é capaz de verificar a assinatura e o body da requisição.
Qualquer espaço, aspas, quebra de linha, será contado como discrepância e essa requisição não será válida.
Como estamos falando de criptografia, não há como “descobrir” o que pode ter gerado a discrepância nas mensagens (recebida e assinada). Não há como analisar se o conteúdo assinado tem algum caractere à mais ou algo assim, apenas se a assinatura é válida ou não.
Como assinar e enviar uma requisição
Abaixo segue um passo a passo para assinar e enviar uma requisição no endpoint que testa a sua assinatura na iugu.
Iremos utilizar o
bash
como exemplo pois assim se aplica globalmente sem precisar saber uma linguagem específica.
Antes de iniciar recomendamos que crie uma pasta especifica pois iremos criar arquivos com alguns comandos e todos precisam estar no mesmo local.
Primeiro passo
Gerar chave privada
$ openssl genrsa -out private.pem 2048
Segundo passo
Gerar chave pública a partir da privada
$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem
Terceiro passo
Copiar chave pública
Para copiar para o clipboard (PARA COLAR NO PAINEL) (somente Mac)
$ pbcopy < public.pem
Para copiar para o clipboard (PARA COLAR NO PAINEL) (somente Windows)
$ clip < public.pem
Criando chave API com assinatura
Para criar a chave API com assinatura, acesse seu painel iugu e clique em Configurações > Integração via API > Novo.
Em seguida, selecione o tipo de Token (PRODUÇÃO ou TESTE).
Adicione uma descrição, para você poder ter seu controle customizável entre suas ApiToken
Cole a chave pública e salve.

Quarto passo
Para enviar uma requisição será necessário ter um body, pois utilizaremos o método POST no endpoint. Esse body você pode criar em um arquivo com o nome conteudo_do_body.txt
Exemplo do conteúdo do arquivo
{
"api_token":"TOKEN CRIADO NO TERCEIRO PASSO",
"mensagem":"qualquer coisa"
}
Salve o arquivo conteudo_do_body.txt
Atenção
Lembre-se de fazer a requisição quando criar o token ou guarde o token contigo em segurança pois ele ficará visível por apenas uma hora na plataforma.
Quinto passo
Será preciso criar um timestamp do momento que enviar a requisição, utilize o seguinte comando para gerar um timestamp com padrão ISO8061
.
Somente Mac
date +"%Y-%m-%dT%H:%M:%S%Z:00"
Somente Linux
date +"%Y-%m-%dT%H:%M:%S%:z"
Anote o resultado, pois iremos utilizar nas etapas seguintes etapas.
Sexto passo
Agora iremos criar um arquivo que será o nosso documento a ser assinado. O padrão de assinatura precisa conter o body da requisição, além de alguns metadados:
- Método
- Endpoint
- Token
- Timestamp
- Body
Crie na sua pasta um arquivo chamado documento.txt, copie o modelo abaixo e preencha com as informações que conseguimos nas etapas anteriores.
Exemplo de como ficariam os dados no momento de fazer a assinatura
POST|/v1/signature/validate
TOKEN CRIADO NO TERCEIRO PASSO|TIMESTAMP CRIADO NO QUINTO PASSO
{
"api_token":"TOKEN CRIADO NO TERCEIRO PASSO",
"mensagem":"qualquer coisa"
}
Obs.: Deixamos apenas duas informações já preenchidas, Método e Endpoint quando fizer uma requisição que não seja apenas para validação será necessário mudar essas informações de acordo com a integração que deseja fazer.
Sétimo passo
Assinar o conteúdo do arquivo documento.txt
usando a chave privada:
$ openssl dgst -sha256 -sign private.pem -out sign.sha256 documento.txt
Esse comando irá criar na pasta em que estiver no terminal um arquivo chamado sign.sha256
.
Oitavo passo
Transformar (encode) para base64 o conteúdo de sign.sha256
criado no quinto passo.
$ openssl base64 -A -in sign.sha256 -out sign.sha256.base64
Esse comando irá criar um novo arquivo sign.sha256.base64.
Nono passo
Copiar o conteúdo de sign.sha256.base64 para usar no Header da requisição.
No Mac
$ pbcopy < sign.sha256.base64
No Windows
$ clip < sign.sha256.base64
O formato do Header deve ficar assim:
Signature: signature=<conteúdo que você copiou acima>
No momento aceitamos o padrão acima apenas com a assinatura, mas já suportamos o formato abaixo e esse deve ser o padrão de todos os clientes.
algorithm=, keyVersion=<versão da key>, signature=<o conteúdo assinado e em base 64>
Exemplo do Header em uma ferramenta de testes de API

O Header deve ter um formato de chave⇒valor assim como na imagem.
Décimo passo
Essa url deve ser inserida na sua ferramenta de testes de API ou como parâmetro no curl
caso não utilize Postman
ou Insomnia
.
https://api.iugu.com/v1/signature/validate

Décimo primeiro passo
Copiar o conteúdo do conteudo_do_body.txt
para usar no body da requisição.
Atenção
Esse é um dos passos mais importantes pois esse arquivo não pode ter sofrido nenhuma alteração desde que você assinou o conteúdo dele utilizando a chave privada. Qualquer alteração resultará em uma resposta de assinatura invalida da API.
No Mac
$ pbcopy < conteudo_do_body.txt
No Windows
$ clip < conteudo_do_body.txt
Agora devemos colar o conteúdo no body da requisição. Repare se o conteúdo do arquivo conteudo_do_body.txt
não foi alterado no momento de colar, alguns editores de texto formatam os arquivos por padrão e ele pode acabar sendo enviado de forma diferente.

Caso veja alguma linha a mais quando copiar, mantenha assim pois o envio da requisição irá considerar inclusive as quebras de linhas, tabs ou qualquer espaço que tenha na mensagem.
Após isso envie a requisição para verificar se a resposta é valida ou não.
Exemplo de resposta com sucesso
{
"message": "Signature check successful",
"request_body": "{\"api_token\":\"TOKEN\",\"message\":\"mensagem qualquer\"}",
"status": "ok"
}

Exemplo de resposta com falha
{
"error": "Invalid signature"
}

Exemplo da requisição usando o Curl:
curl --request POST \\
--url https://api.iugu.com/v1/signature/validate \
--header 'Content-Type: application/json' \
--header 'Request-Time: 2022-06-08T15:35:06-03:00' \
--header 'Signature: algorithm=RSA256, keyVersion=0, signature={{signature}}' \\
--data '{
"api_token":"{{api_token}}",
"message":"mensagem qualquer"
}'
Referências
Gerar chave RSA pelo terminal (inglês): https://rietta.com/blog/openssl-generating-rsa-key-from-command/
Manual base64: https://en.wikipedia.org/wiki/Base64
Assinatura digital pelo alipay (inglês): https://global.alipay.com/docs/ac/ams/digital_signature
Assinar e verificar openssl pelo terminal (inglês): https://www.zimuel.it/blog/sign-and-verify-a-file-using-openssl
Como explicar assinaturas com chave pública para leigos (inglês): https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/
Padrão ISO 8601 para tempo (inglês): https://www.iso.org/iso-8601-date-and-time-format.html