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:

  1. HTTP Basic Auth: Método recomendado.
  2. Bearer Authentication: Segunda opção.
  3. API Token como Parâmetro: Enviado como api_token.

Tipos de tokens

Há quatro tipos de tokens na iugu:

TipoUse para
live_tokenAções em ambiente de produção
test_tokenAções em ambiente de teste (homolgação/sandbox)
master_tokenCriar e/ou Listar API Tokens
usar_tokenAutenticar-se à nível usuário

user_token

Utilize para as rotas:

Referência da rotaRota
Enviar verificação de Subcontav1/accounts/{account_id}/request_verification
Editar Subcontav1/accounts/{id}
Remover API Tokenv1/{account_id}/api_tokens/{id}
Renovar API Token de Usuáriov1/profile/renew_access_token

master_token

Utilize para as rotas:

Referência da rotaRota
Criar API Tokenv1/{account_id}/api_tokens
Listar API Tokens das Subcontasv1/{account_id}/api_tokens

🚧

Importante

  • O user_token é acessível apenas no retorno 200 OK da API Criar Subcontav1/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

  1. Acesse alia.iugu.com
  2. Clique em Configurações > Integração via API > Novo




  1. Escolha entre produção (live), teste (test) ou mestre* (master)
    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.
  2. Escolha uma Descrição para seu novo api_token (e.g. Meu Token)
  3. Clique em salvar.
  4. Os Administradores da Conta serão notificados para aprovar este api_token. Enquanto não aprovado, não será possível utilizá-lo, retornando 401 Unauthorized.

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:

APIEndpoint
Transferências para Terceirosv1/transfer_requests
Pedido de Saque/Transferências Própriasv1/accounts/{id}/request_withdraw
Transferir Valorv1/transfers
Criar Pedido de Pagamentov1/payment_requests
Validate Signaturev1/signature/validate
Criar Subcontav1/marketplace/create_account
Configurar Contav1/accounts/configuration
Adicionar domicílio bancáriov1/bank_verification
Criar API Tokenv1/{account_id}/api_tokens
Listar API Tokensv1/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.


O que mais?