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

Tipos de autenticação

Diferenças entre os tokens

Criando suas chaves de API via painel

Como criar os tokens via API

Como utilizar o live_token e o test_token

Assinatura de Requisições (RSA)

Tipos de autenticação

A autenticação na iugu é realizada por meio de uma chave de API, que permite ao sistema identificar a sua conta e conceder as permissões necessárias para a comunicação com a iugu em nome da conta associada.

Existem três métodos de autenticação disponíveis, sendo o mais recomendado o uso do HTTP Basic Auth. A segunda opção é a autenticação por Bearer Authentication. A terceira alternativa é enviar o API Token como um parâmetro denominado api_token.

`live_token`, `test_token`, `user_token` e `master_token`

live_token: utilize-o para ações em ambiente produção.
test_token: utilize-o para ações em ambiente de teste (homologação/sandbox).
master_token: utilize-o para Criar e/ou Listar API Tokens
user_token: utilize-o para requisições à endpoints que requiram uma autenticação a nível usuário.

Rotas que utilizam `user_token` ou `master_token`

master_token

Referência da API	Endpoint
Criar API Token	`v1/{account_id}/api_tokens`
Listar API Tokens	`v1/{account_id}/api_tokens`

user_token

Referência da API	Endpoint
Remover API Token	`v1/{account_id}/api_tokens/{id}`
Renovar API Token de Usuário	`v1/profile/renew_access_token`
Atualizar Subconta	`v1/accounts/{id}`
Enviar verificação de Subconta	`v1/accounts/{account_id}/request_verification`

Como ter acesso ao `user_token`?

No retorno 200 OK do endpoint Criar Subconta — v1/marketplace/create_account.
Ou no retorno 200 OK do endpoint Listar API Tokens das subcontas — v1/retrieve_subaccounts_api_token.

🚧
Importante

Os endpoints Criar Subconta e Listar API Tokens das subcontas são requisitadas, exclusivamente, pela Conta Mestre.

Utilize o master_token

Criar `api_token`

Há duas formas de criar um api_token:

Via Alia
Via API

Alia

Acesse alia.iugu.com > Configurações
Integrações API > Novo
Escolha entre Teste, Produção ou Mestre*.
1. Obrigatório: Durante a criação, utiliza-se a tecnologia de Autenticação RSA.
2. Opcional: É possível cadastrar uma lista de IPs dedicados ou Dinâmicos. Entre em contato com o nosso Time de Suporte para cadastrá-los.
Dê uma descrição. Por exemplo: "Minha chave API"
Clique em Salvar.

🚧
Importante

Este api_token ficará visível por apenas 1h. Após isso, será censurado.

A criação de api_tokens dependem de uma aprovação enviada para os Administradores da Conta.

API

Utilize o endpoint Criar API Token — v1/{account_id}/api_tokens.

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/27016E1AD888499A98994E781B6C3762/api_tokens?api_token=your-api_token' \
     --header 'Request-Time: 2025-03-12T14:58:01-03:00' \
     --header 'Signature: signature=nGDVNcBXfQ8kkGM2I/0XHDOOI0v6NCJCFzsm9TkZ3t1gihHDLUSpGY2/squfwxRMXpLBibdcMFH5ZS4xsadE7vuHnaJWYaXzsjMk9a5sM2kCPt1VAG4kmrRaToSoeXe6NrH96hASS1IXywzTPJJl/TbxV0i9uXzl0THRQ/BLSAmKZyEpATMdN5pWLFnohYfXjQ40w7W3Q4u/OzhWKGaGEOi9zkgqI89KHinci+7s90h/N8ttsmR+Ira8raWI6XMBKfbPuOYjuLKaZiNBce9+MkphRGFPlYw0uzSoiLzONtoCWoETrtPdMSKpSQQFU/yWMxIs/+Koav8jF2HsVcl/tg==' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "api_type": "LIVE",
  "description": "Meu token de produção"
}
'

{
  "id": "8D3EA0B0F546405B880F1BAC7B2CA5A7",
  "token": "ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0",
  "api_type": "LIVE",
  "description": "Meu token de produção",
  "created_at": "2025-03-12T15:00:22-03:00",
  "status": "active"
}

Dica de segurança 🔐

Recomendamos a atualização da sua chave de API a cada 30 dias. Manter a chave atualizada é fundamental para evitar seu uso indevido em caso de vazamento de informações.

Não se esqueça de que sua chave de API funciona como uma senha, sendo ela responsável por autorizar suas transações de forma automática e autenticada.

Como utilizar o `live_token` e o `test_token`

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.

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 ''

Autenticação com Assinatura RSA

O que é Assinatura RSA?

Uma Assinatura RSA em APIs é um método de criptografia que utiliza o algoritmo RSA para garantir a autenticidade e a integridade das mensagens trocadas entre um cliente e um servidor. Ela envolve a criação de uma assinatura digital usando uma chave privada, que pode ser verificada por qualquer pessoa com a chave pública correspondente. Isso assegura que a mensagem foi enviada por uma fonte confiável e que não foi alterada durante a transmissão.

Endpoints obrigatórios

Os endpoints que têm como características Cash Out, criação de conta e API Tokens, por exemplo, requerem essa autenticação. São eles:

Prefere um vídeo ensinando como faz?

Assista nosso Webinar conduzido por um dos nossos Engenheiros:

Que tal uma Recipe?🧪

Aqui está uma sugestão de como o seu script pode ser desenvolvido:

`Ruby on Rails`

`Node.js`

`PHP`

`Python`

`Java`

Antes de começar ⚠️

Alguns pontos importantes antes de começar:

É possível apenas em produção (live_mode)
É permitido apenas um api_token criptografado por conta.
Necessário ter acesso ao Alia para a etapa de criação do api_token.
1. Não é possível utilizar o endpoint Criar API Token — v1/{account_id}/api_tokens como alternativa, pois este também requer RSA.
Este processo exige a utilização de OpenSSL.
Crie uma pasta que armazenará os arquivos do OpenSSL.
Navegue até esta pasta utilizando o cmd

Após estas etapas, continue com este artigo.

Usuários Linux

Comandos de copy serão utilizados neste passo a passo. Certifique-se de que o xclip ou xsel está instalado no seu sistema. Você pode instalar com:

$ sudo apt-get install xclip

ou

$ sudo apt-get install xsel

Fluxo Whitelabel

Para estruturas de Marketplace (subcontas), é possível seguir as etapas deste guia e refletir para as subcontas atreladas à Mestre, descartando a necessidade de fazê-la uma a uma.

Para isso, siga as etapas de 1 a 4 na Conta Mestre e, nas etapas de 5 a 12, e onde for solicitado o "api_token criptografado", insira o live_api_token da subconta, por mais que ele não seja criptografado.

Ilustração do Fluxo

O que precisará ter?

Uma subconta com um live_api_token
A Conta Mestre desta Subconta com um api_token criptografado.

Continue com este artigo.

1. Gerar chave privada

No cmd, insira este comando:

$ openssl genrsa -out private.pem 2048

2. Gerar chave pública

Ainda no cmd, insira o comando abaixo para gerar a chave pública a partir da chave privada

$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem

3. Copiar a chave pública

Copie para o clipboard a chave pública gerada:

Windows

$ clip < public.pem

macOS

$ pbcopy < public.pem

Linux (xclip)

xclip -selection clipboard < public.pem

Linux (xsel)

$ xsel --clipboard < public.pem

4. Colar chave pública no painel

Acesse alia.iugu.com
Configurações > Integrações via API
Clique em Novo > e, em Tipo, selecione Produção
Dê uma descrição para esta chave (exemplo: Minha chave RSA)
Abaixo de descrição, cole a chave pública mantendo os cabeçalhos ----BEGIN PUBLIC KEY---- e ----END PUBLIC KEY----
Clique em Salvar.

Esta chave será identificada como Chave criptografada.

🚧
Importante

A criação de api_tokens dependem de uma aprovação enviada para os Administradores da Conta.

Guarde o api_token gerado em um lugar seguro

Body = `raw`

Assine o corpo da requisição de forma bruta (raw), sem qualquer tratamento ou parse. O payload assinado deve ser idêntico ao enviado na requisição. A assinatura gerada deve ser criptografada em base64 e incluída na requisição.

O restante permanece inalterado: o corpo da requisição deve conter o api_token e todos os campos necessários, sem qualquer alteração no processo usual.

❗️
Quebra de Linhas
Ao montar o arquivo no Windows, não utilize editores no terminal, como Vim, Nano, etc. Qualquer espaço, aspas, quebra de linha, invalidará a requisição.
Recomendamos a utilização de editores de texto como Notepad++, VSCode ou, até mesmo, o próprio Bloco de Notas, que permitem a visualização das quebras das delinha CR LF, LF e CR, que variam entre Sistemas Operacionais.

5. Assinar e enviar requisição

Com a chave criptografada criada em sua conta (etapa 1 ao 4), continue com este artigo para a Assinatura da Requisição.

Atenção ⚠️

As próximas etapas servem para simular os processos técnicos e o seu resultado. A forma de implantá-la fica à critério do cliente/seller.

As etapas de 5 ao 12 devem ser realizadas para todas as requisições, sem exceção.

Timestamp padrão `ISO8061` e UTC

O timestamp segue os padrões ISO8061. O UTC deve ser o mesmo do servidor que esta solução será hospedada.

Utilize os comandos abaixo para gerar um timestamp nos padrões ISO8061:

macOS

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

Linux

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

🚧
Tolerância de 5 minutos
O timestamp inserido no documento tem uma tolerância de até 5 minutos. Por exemplo: 2024-06-15T12:55:00-03:00, só é possível enviar a requisição até 12:59:59. Se exceder, retornará Invalid Signature

5.1 Criar arquivo `.txt`

Crie um arquivo .txt com nome 'documento' em sua pasta (etapa 5 de Atenção ⚠️)
Para cada endpoint, escreva o body no 'documento', seguindo, exatamente, os padrões a seguir:

Linha	Conteúdo	Exemplo
1	Método\|endpoint	POST\|/v1/signature/validate
2	api_tokencriptografado\|timestamp	1AB1CD2EF1BC9DE0165FC37268331E1A4A0D8FCF90E2C42AB4100CBDB86E5136\|2024-06-15T12:21:29-03:00
3	`body` da requisição sem espaço	{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}

Importante ⚠️

A linha 3 não deve conter nenhum espaço, a não ser que seja o valor de um parâmetro, por exemplo "Nome da Subconta". Este pode conter espaços, pois é um valor e não interferirá.

O resultado do exemplo acima é:

POST|/v1/signature/validate
1AB1CD2EF1BC9DE0165FC37268331E1A4A0D8FCF90E2C42AB4100CBDB86E5136|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}

Observações — Whitelabel

Na linha 2: Informe o live_pi_token da subconta.

Exemplos de `documento.txt` de cada endpoint

Os scripts abaixo são exemplos de como o seu documento deve ser escrito para ser assinado:

Criar API Token — `POST` `/v1/{account_id}/api_tokens`

POST|/v1/12345A1BC666499D98994A781E6C3762/api_tokens
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2025-03-12T14:58:01-03:00
{"api_type":"LIVE","description":"Meu Token de produção"}

Transferir Valor — `POST` `v1/transfers`

POST|/v1/transfers
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"receiver_id":"id-da-conta","amount_cents":100}

Transferência para Terceiros — `POST` `v1/transfers_requests`

POST|/v1/transfer_requests
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"receiver":{"pix":{"type":"email","key":"iugu@iugu.com"},"name":"Nome","cpf_cnpj":"113.436.750-30"},"transfer_type":"pix","amount_cents":100}

Pedido de Saque/Transferências Próprias — `POST` `v1/accounts/{id}/request_withdraw`

POST|/v1/accounts/id-da-subconta/request_withdraw
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"amount":10}

Validate Signature — `POST` `v1/signature/validate`

POST|/v1/signature/validate
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"RAW_BODY":"string"}

Criar Subconta — `POST` `v1/marketplace/create_account`

POST|/v1/marketplace/create_account
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}

Configurar Conta — `POST` `v1/accounts/configuration`

POST|/v1/accounts/configuration
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"auto_withdraw":true,"auto_advance":false}

Adicionar domicílio bancário — `POST` `/v1/bank_verification`

POST|/v1/bank_verification
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"agency":"0000","account":"000000","account_type":"cc","bank":"001"}

Criar Pedido de Pagamento — `POST` `v1/payment_requests`

POST|/v1/payment_requests
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"barcode":"846100000013310502962023004200030007003752691117","document_amount_cents":10,"amount_cents":10}

5.2 Salvar arquivo

Após informações inseridas, salve este arquivo e não altere-o mais.

6. Assinar `documento.txt` usando Chave privada

No cmd, insira o seguinte comando:

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

7. Transformar em `base64`

Insira o comando abaixo para transformar (encode) para base64 o conteúdo do arquivo sign.sha256 de sua pasta:

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

📘
sign.sha256.base64
Após executá-lo, cria-se um novo arquivo de nome sign.sha256.base64 na mesma pasta.

8. Copiar conteúdo `sign.sha256.base64`

Insira o comando para copiar para o clipboard o conteúdo que será utilizado no header — Signature — da requisição

Windows

clip < sign.sha256.base64

macOS

$ pbcopy < sign.sha256.base64

Linux (xclip)

xclip -selection clipboard < sign.sha256.base64

Linux (xsel)

$ xsel --clipboard < sign.sha256.base64

9. Preparar o `URL`

Utilize um dos endpoints (de acordo com a etapa 5.1) que deseja e atente-se às seguintes informações:

Neste exemplo, foi escolhido o endpoint de Transferência para Terceiros — v1/transfer_requests, então, preencha de acordo com a sua requisição:

https://api.iugu.com/v1/transfer_requests?api_token=api_tokencriptografado

10. Copiar o `body` do `documento.txt`

Copie apenas a terceira linha do documento.txt:

{"receiver_id":"id-da-conta","amount_cents":100,"api_token":"api_tokencriptografado"}

Como o header deve ficar?

Preencha os parâmetros do header no padrão 'parâmetro=valor' de acordo com estas instruções:

Parâmetro	O que preencher	Valor (exemplo)
`Signature`	o conteúdo copiado da etapa 8	`signature=sequência-de-caracteres`
`Request-Time`	Timestamp gerado no momento da assinatura	`2024-06-15T12:21:29-03:00`
`Accept`	o tipo de resposta esperada do servidor	`application/json`
`Content-Type`	o formato dos dados enviados no body da requisição	`application/json`

11. Colar o conteúdo no `body`

Com o conteúdo do body copiado (etapa 10), cole no corpo da requisição.

🚧
Verifique se houve alteração
Alguns editores de texto formatam os arquivos por padrão e isso poderá invalidar a assinatura (Invalid Signature). Se alterado, utilize o Bloco de Notas, VSCode ou Notepad++.

12. Enviar requisição

Certifique-se de ter seguido estritamente todos os passos deste guia e, por fim, requisite o endpoint escolhido.

Verificar se assinatura é válida (opcional)

Utilize o endpoint Validate Signature — v1/signature/validate para verificar se a assinatura gerada (etapa 7 e 8) é válida. Ou seja, esta rota não torna uma assinatura válida, apenas a verifica.

Este endpoint segue a mesma lógica das etapas 5 até 12, então, siga-os para requisitá-lo.

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/signature/validate?api_token=api_tokencriptografado' \
     --header 'Request-Time: 2024-06-15T12:21:29-03:00' \
     --header 'Signature: signature=sequência-de-caracteres' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{"RAW_BODY": "Validando a integração"}'

{
  "message": "Signature check successful",
  "request_body": "{\n  'api_token':'<api_token-criptografado>',\n  'message':'anything'\n}",
  "status": "ok"
}

`Signature check successful`

O retorno "message": "Signature check successful" serve apenas para validar que o seu script seguiu a lógica correta.

Importante ⚠️

Este é o único endpoint que o Fluxo Whitelabel não é compatível.

Erros

Os erros de criptografia são sucintos por, justamente, serem criptografados. Apesar disso, há erros que têm uma explicação. Veja-os abaixo:

Erro	Motivo(s)/hipótese(s)
`Public Key Not Found`	O `documento.txt` não foi criado no mesmo servidor que a aplicação está hospedada. Chave criptografada na Conta Mestre pode ter sido criada de forma incorreta. Se a requisição for com api_token de uma subconta, é obrigatório que tenha sido criado a chave pública na Conta Mestre
`Invalid Elepsed Time`	Data do `Request-Time` está diferente da data enviada no arquivo. Ultrapassou os 5 minutos (saiba mais) O minuto do servidor está divergente do mundial. Ao criar o timestamp em `ISO8061`, automaticamente, é convertido para GMT+03:00. Se trata de um padrão mundial alterar apenas o horário.
`Invalid Signature`	O `documento.txt` está diferente da requisição Há uma quebra de linha (manual ou durante o processo) No código, a quebra de linha está como `/r/n` (deve ser `\r\n`) Para cada requisição, deve-se criar um novo `documento.txt` com os dados da requisição em questão Algumas aplicações quebram o `documento.txt` (saiba mais)

Referências técnicas

Algumas referências para fins de conhecimento: