📘

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,
• Listar API Tokens,
• Remover API Token.

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:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. 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:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:
   Base64 dessa chave: NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. 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

Criação de Chave Criptografada na Conta Mestre

O dono da conta (ou responsável técnico) ficará encarregado de criar uma Chave Criptografada na plataforma Alia. Esta ação é realizada única e exclusivamente através da plataforma.

Através desta chave, será possível realizar uma assinatura digital, ou "Signature" que é um pré-requisito para a utilização do recurso de Pix/TED-Out (Transferência para Terceiros). Portanto, TENHA CUIDADO com a integridade de suas chaves pública e privada.

Siga os passos abaixo para criar uma Chave Criptografada:

📘

$ =

Iremos utilizar o bash como base para o exemplo, pois pode ser aplicado de forma global, sem necessidade de conhecimento em alguma linguagem de programação específica.
Antes de iniciar, recomendamos que crie uma pasta especifica em seu sistema, pois iremos criar arquivos com alguns comandos e todos precisam estar no mesmo local. Se você irá trabalhar com Subconta, recomendamos que crie uma pasta para cada Subconta.

Primeiro passo

• Para este e outros passos, precisaremos usar o OpenSSL, ferramenta utilizada para implementar funções básicas de criptografia.
• Após instalar e acessar a pasta do OpenSSL pelo seu terminal, insira o comando abaixo para gerar a Chave Privada:

$ openssl genrsa -out private.pem 2048

Segundo passo

• Gerar chave pública a partir da chave privada. Insira o comando:

$ 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 Windows)

$ clip < public.pem

Para copiar para o clipboard (PARA COLAR NO PAINEL) (somente Mac)

$ pbcopy < public.pem

• Exemplo de chave Pública com extensão .pem:

Note que inicia com ----BEGIN PUBLIC KEY----- e termina com ----END PUBLIC KEY----

Quarto passo

• Criando chave API com chave pública:
  Para criar a chave API criptografada, acesse seu painel iugu e clique em Configurações > Integração via API > Novo.
• Em seguida, selecione o tipo de Token (precisa ser PRODUÇÃO).
  Adicione uma descrição para ajudar a identificar sua chave, cole a chave pública e salve.

• Exemplo de Chave Criptografada:

Seguindo o padrão dos outros tokens da iugu, esta Chave Criptografada ficará oculta 1 hora após a sua criação, então guarde-a com segurança!

Obs: Caso o campo para colar a chave pública em sua plataforma não esteja habilitado, entre em contato com nossa equipe de Suporte.

Assinando e enviando a requisição

Quinto passo

• Agora que você tem uma Chave Criptografada de Produção criada na sua conta mestre, podemos seguir para o processo de Assinatura de Requisição. Começando com a preparação do arquivo que será usado no processo de assinatura da requisição para a transferência. Alguns pontos importantes:

❗️

Atenção à quebras de linha

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.

Recomendamos a utilização de algum editor de texto (Notepad++, VSCode) que permita a alteração e visualização das quebras de linha 'CR LF, LF e CR', que podem variar entre sistemas.

👉

Body = raw!

É 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 api_token e cada campo necessário para dada requisição,  sem necessidade de nenhum processo diferente do que já ocorre normalmente.

Atenção, os passos abaixo servem para simular os processos técnicos e a estrutura que irá resultar na 'Signature', que será então utilizada para a Transferência de Terceiros. A forma de implantação fica à critério do cliente. Acesse nossa Biblioteca/SDK de RSA.

• Crie na sua pasta um arquivo chamado documento.txt. Este documento deverá ser composto no padrão informado abaixo:

Linha 1 - Método|Endpoint

Linha 2 - Chave Criptografada|Timestamp - Data e hora no padrão ISO8061. Além da assinatura, este 'valor' deve ser obrigatoriamente enviado no Header da requisição de transferência. A data e hora contida no arquivo assinado deve ser exatamente a mesma presente no Header da requisição de transferência. Caso a requisição seja enviada 5 minutos após o horário 'assinado', a requisição de transferência irá falhar, e será necessário assinar o documento novamente com o horário atualizado.

Linha 3 - Raw body da requisição - Recomendamos que deixem todo o conteúdo da requisição na terceira linha, evitando quebras de linhas desnecessárias.

• Veja abaixo um exemplo de um arquivo preenchido:

POST|/v1/transfer_requests
chavecriptografada|2023-04-13T09:05:29-03:00
{  "receiver": {    "pix": {      "type": "cpf",      "key": "11111111111"    }  },  "api_token": "chavecriptografada",  "transfer_type": "pix",  "amount_cents": 100,  "description": "teste"}

Obs: Para criar um timestamp com padrão ISO8061no momento da assinatura/transferência, utilize o seguinte comando:

Somente Mac

date +"%Y-%m-%dT%H:%M:%S%Z:00"

Somente Linux

date +"%Y-%m-%dT%H:%M:%S%:z"

• Salve o arquivo documento.txt em sua pasta.

Sexto passo

• Assinar o conteúdo do arquivo documento.txt usando a chave privada:

$ openssl dgst -sha256 -sign private.pem -out sign.sha256 documento.txt

• Este comando irá criar um arquivo chamado sign.sha256. na pasta em que estiver no terminal.

Sétimo passo

• Transformar (encode) para base64 o conteúdo de sign.sha256 criado no sexto passo:

$ openssl base64 -A -in sign.sha256 -out sign.sha256.base64

• Esse comando irá criar um novo arquivo sign.sha256.base64 na pasta.

Oitavo passo

• O próximo passo será copiar o conteúdo de sign.sha256.base64 para usar no Header da requisição. Este valor conteúdo conteúdo é sua signature que será usada na transferência.

Somente Windows

$ clip < sign.sha256.base64

Somente MAC

$ pbcopy < sign.sha256.base64

• O formato do Header deve ficar assim:

algorithm=, keyVersion=<versão da key>, signature=<o conteúdo assinado e em base 64>

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.

• Exemplo no Postman:

• O Header deve ter um formato de chave=valor assim como na imagem.

Nono passo

• Preparando a requisição. A URL abaixo 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/transfer_requests

Décimo passo

• Copiar o conteúdo da Linha 3 do arquivo documento.txt para usar no body da requisição:

{  "receiver": {    "pix": {      "type": "cpf",      "key": "11111111111"    }  },  "api_token": "chavecriptografada",  "transfer_type": "pix",  "amount_cents": 100,  "description": "teste"}

🚧

Atenção

Este é um dos passos mais importantes deste fluxo, pois o arquivo documento.txt não pode ter sofrido nenhuma alteração desde que você assinou o conteúdo dele utilizando a chave da Subconta. Qualquer alteração resultará em uma resposta de assinatura invalida da API. Mais detalhes sobre o teste de validação da assinatura abaixo.

Décimo primeiro passo

• Agora devemos colar o conteúdo no body da requisição. Repare se o conteúdo do arquivo documento.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.

Décimo segundo passo

• Envie a requisição. Veja exemplo no Postman:

Validando a Signature

• Através da Endpoint abaixo, é possível validar se a assinatura gerada através do fluxo de Assinatura Digital, é valida.

https://api.iugu.com/v1/signature/validate

• 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"
}'

📘

Documentações Relacionadas - Transferência Para Terceiros

• Documentação Técnica - Caso de uso, requisitos e informações de retorno, etc
• DOC API - Realizar Transferência
• DOC API - Consulta de Transferência Para Terceiros
• DOC API - Consulta de Comprovante de Pix-Out
• DOC API - Listar Comprovantes de Pix-Out

👍

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