📘
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 em base64 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 o ApiToken não possuir public_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

📘O que você irá aprender com esse artigo?

Tipos de autenticação

Diferença entre os tokens

📘Toggle de Produção/Teste no painel

Criando suas chaves de API (API Tokens) via painel

❗️Trate suas chaves de API como senhas

🚧Dica de segurança

Como criar os tokens via API

Como utilizar o live_token e o test_token nas chamadas API

HTTP Basic Auth

📘HTTP Basic Auth

Bearer Authentication

📘Bearer Authentication

🚧Boas práticas

Assinatura de Requisições (RSA)

Introdução

📘Este tipo de criptografia tem 3 elementos

🚧Atenção

Assinando requisição na iugu

🚧Libs disponíveis!

🚧

📘Validando a assinatura pela iugu

❗️

Como assinar e enviar uma requisição

📘

Primeiro passo

Segundo passo

Terceiro passo

Criando chave API com assinatura

Quarto passo

🚧Atenção

Quinto passo

Sexto passo

Sétimo passo

Oitavo passo

Nono passo

Décimo passo

Décimo primeiro passo

🚧Atenção

👍Referências

📘
O que você irá aprender com esse artigo?

📘
Toggle de Produção/Teste no painel

❗️
Trate suas chaves de API como senhas

🚧
Dica de segurança

📘
HTTP Basic Auth

📘
Bearer Authentication

🚧
Boas práticas

📘
Este tipo de criptografia tem 3 elementos

🚧
Atenção

🚧
Libs disponíveis!

📘
Validando a assinatura pela iugu

🚧
Atenção

🚧
Atenção

👍
Referências