📘

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:

user_token

Utilize para as rotas:

master_token

Utilize para as rotas:

🚧

Importante

• O user_token é acessível apenas no retorno 200 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

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

3. 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.
4. Escolha uma Descrição para seu novo api_token (e.g. Meu Token)
5. Clique em salvar.
6. 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.

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:

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.