Tokens de Autenticação
Saiba como obter acesso aos API tokens.
O que você vai aprender com este artigo?
- Tipos de tokens de autenticação disponíveis (live_token, test_token, user_token)
- Como criar e gerenciar tokens via API
- Como utilizar a autenticação com Assinatura RSA
A autenticação na iugu é feita através de uma chave de API, que identifica a conta e concede permissões para comunicação.
Há três métodos de autenticação disponíveis:
- HTTP Basic Auth: Método recomendado.
- Bearer Authentication: Segunda opção.
- API Token como Parâmetro: Enviado como
api_token
.
Tipos de tokens
Há quatro tipos de tokens na iugu:
Tipo | Use para |
---|---|
live_token | Ações em ambiente de produção |
test_token | Ações em ambiente de teste (homolgação/sandbox) |
master_token | Criar e/ou Listar API Tokens |
usar_token | Autenticar-se à nível usuário |
user_token
user_token
Utilize para as rotas:
Referência da rota | Rota |
---|---|
Enviar verificação de Subconta | v1/accounts/{account_id}/request_verification |
Editar Subconta | v1/accounts/{id} |
Remover API Token | v1/{account_id}/api_tokens/{id} |
Renovar API Token de Usuário | v1/profile/renew_access_token |
master_token
master_token
Utilize para as rotas:
Referência da rota | Rota |
---|---|
Criar API Token | v1/{account_id}/api_tokens |
Listar API Tokens das Subcontas | v1/{account_id}/api_tokens |
Importante
- O
user_token
é acessível apenas no retorno200
OK
da API Criar Subconta —v1/marketplace/create_account
para todas as subcontas criadas a partir do mês 05/24.- Para contas antes desta data, utilize o endpoint Listar API Tokens das subcontas —
/v1/retrieve_subaccounts_api_token
Criar Token
Há duas formas de criar api_tokens
na iugu:
1. Via Alia
- Acesse alia.iugu.com
- Clique em Configurações > Integração via API > Novo

- Escolha entre produção (
live
), teste (test
) ou mestre* (master
)- Obrigatório: Durante a criação, utiliza-se a tecnologia de Autenticação RSA.*
- Opcional: É possível cadastrar uma lista de IPs dedicados ou Dinâmicos. Entre em contato com o nosso Time de Suporte para cadastrá-los.
- Escolha uma Descrição para seu novo
api_token
(e.g. Meu Token) - Clique em salvar.
- Os Administradores da Conta serão notificados para aprovar este
api_token
. Enquanto não aprovado, não será possível utilizá-lo, retornando401
Unauthorized
.
2. Via Criar API Token
Utilize a rota POST
/v1/{account_id}/api_tokens
. Informe os parâmetros:
Path
account_id
Body
api_type
description
Importante
Este endpoint requer o
user_token
em sua autenticação.
Requisição exemplo
curl --request POST \
--url 'https://api.iugu.com/v1/27016E1AD888499A98994E781B6C3762/api_tokens?api_token=1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF' \
--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": "21E440F2AC8A4EB89CAB9AB75CA60C96",
"token": "1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF",
"api_type": "LIVE",
"description": "Descrição",
"created_at": "2024-09-02T21:03:18-03:00",
"status": "active"
}
Importante ⚠️
Guarde este api_token
. Ele ficará visível por apenas 1h. Após isso, será mascarado 😷 e não haverá mais como recuperá-lo.
Requisição com Assinatura RSA
Assinatura RSA
A Assinatura RSA é um método de criptografia que usa o algoritmo RSA para autenticar e garantir a integridade das mensagens entre cliente e servidor, através de uma assinatura digital criada com uma chave privada e verificável com uma chave pública.
Endpoints obrigatórios
Os endpoints que requerem esse nível autenticação são:
API | Endpoint |
---|---|
Transferências para Terceiros | v1/transfer_requests |
Pedido de Saque/Transferências Próprias | v1/accounts/{id}/request_withdraw |
Transferir Valor | v1/transfers |
Criar Pedido de Pagamento | v1/payment_requests |
Validate Signature | v1/signature/validate |
Criar Subconta | v1/marketplace/create_account |
Configurar Conta | v1/accounts/configuration |
Adicionar domicílio bancário | v1/bank_verification |
Criar API Token | v1/{account_id}/api_tokens |
Listar API Tokens | v1/retrieve_subaccounts_api_token |
Como assinar suas requisições?
Consulte a documentação Autenticação com Assinatura RSA. Nela está presente um Webinar e também uma Recipe de como implantar esta solução em seu script
.
Updated 18 days ago