📘

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á três tipos de tokens na iugu:

live_token

Utilize para ações em ambiente de produção.

test_token

Utilize para ações em ambiente de teste (homolgação/sandbox)

user_token

Token de nível usuário. Utilize para requisitar as APIs a seguir:

API tokens

Atualização e Verificação de Subconta

🚧

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 — /v1/{account_id}/api_tokens ou 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) ou Teste (test)
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.

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/1ABC234567890DEF1ABC234567890DEF/api_tokens?api_token=1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "api_type": "LIVE",
  "description": "Descrição"
}
'

Response exemplo

{
  "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.