---
updatedAt: 2026-07-30T14:51:01.000Z
agentTools:
  projectIndex: https://dev.iugu.com/llms.txt
---

# Tokens de Autenticação

Saiba como obter acesso aos API tokens.

<Callout icon="📘" theme="info">
  ### 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
</Callout>

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:

| Tipo           | Use para                                         |
| :------------- | :----------------------------------------------- |
| `live_token`   | Ações em ambiente de produção                    |
| `test_token`   | Ações em ambiente de teste (homologação/sandbox) |
| `master_token` | Criar, Remover e Listar API Tokens               |
| `user_token`   | Autenticar-se à nível **usuário**                |

## `user_token`

Utilize para as rotas:

| Referência da rota                                                                                        | Rota                                            |
| :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------- |
| [Enviar verificação de Subconta](https://dev.iugu.com/reference/enviar-verifica%C3%A7%C3%A3o-de-subconta) | `v1/accounts/{account_id}/request_verification` |
| [Editar Subconta](https://dev.iugu.com/reference/atualizar-subconta)                                      | `v1/accounts/{id}`                              |
| [Renovar API Token de Usuário](https://dev.iugu.com/reference/renovar-api-token-de-usuario)               | `v1/profile/renew_access_token`                 |

## `master_token`

Utilize para as rotas:

| Referência da rota                                                       | Rota                              |
| :----------------------------------------------------------------------- | :-------------------------------- |
| [Criar API Token](https://dev.iugu.com/reference/criar-token-de-api)     | `v1/{account_id}/api_tokens`      |
| [Listar API Tokens](https://dev.iugu.com/reference/listar-api-tokens)    | `v1/{account_id}/api_tokens`      |
| [Remover API Token](https://dev.iugu.com/reference/remover-token-de-api) | `v1/{account_id}/api_tokens/{id}` |

<Callout icon="🚧" theme="warn">
  ### Importante

  - O `user_token` é acessível apenas no retorno `200` `OK` da API [Criar Subconta](https://dev.iugu.com/reference/criar-subconta) — `v1/marketplace/create_account`.
</Callout>

***

# Criar Token

Há duas formas de criar `api_tokens` na iugu:

### 1. Via <Glossary>Alia</Glossary>

1. <Glossary>Acesse</Glossary> [alia.iugu.com](https://alia.iugu.com/)
2. Clique em Configurações > Integração via API > **Novo**

<Image src="https://files.readme.io/f179e12d988d83e57bc9f3810328cddb611a8fcbdd0dc42d6f01c3277af04181-image.png" align="left" wrap={true} />

<br />

<br />

<br />

<br />

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.](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#o-que-%C3%A9-assinatura-rsa)\*
   2. **Opcional:**  É possível cadastrar uma lista de IPs dedicados ou Dinâmicos. [Entre em contato com o nosso Time de Suporte](https://support.iugu.com/hc/pt-br/requests/new) 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](https://dev.iugu.com/reference/criar-token-de-api)

Utilize a rota `POST` `/v1/{account_id}/api_tokens`. Informe os parâmetros:

### Path

* `account_id`

### Body

* `api_type`
* `description`

<Callout icon="🚧" theme="warn">
  ### Importante

  Este endpoint requer o `master_token` em sua autenticação.
</Callout>

### Requisição exemplo

```shell cURL
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"
}
'
```
```json Response
{
  "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 :mask: 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:

| Referência da rota                                                                                  | Endpoint                            |
| :-------------------------------------------------------------------------------------------------- | :---------------------------------- |
| [Transferências para Terceiros](https://dev.iugu.com/reference/transfer%C3%AAncia-para-terceiros-1) | `v1/transfer_requests`              |
| [Pedido de Saque/Transferências Próprias](https://dev.iugu.com/reference/pedido-de-saque)           | `v1/accounts/{id}/request_withdraw` |
| [Transferir Valor](https://dev.iugu.com/reference/transferir-valor)                                 | `v1/transfers`                      |
| [Criar Pedido de Pagamento](https://dev.iugu.com/reference/criar-pedido-de-pagamento)               | `v1/payment_requests`               |
| [Validate Signature](https://dev.iugu.com/reference/validate-signature)                             | `v1/signature/validate`             |
| [Criar Subconta](https://dev.iugu.com/reference/criar-subconta)                                     | `v1/marketplace/create_account`     |
| [Configurar Conta](https://dev.iugu.com/reference/configurar-conta)                                 | `v1/accounts/configuration`         |
| [Adicionar domicílio bancário](https://dev.iugu.com/reference/adicionar-domicilio-bancario)         | `v1/bank_verification`              |
| [Criar API Token](https://dev.iugu.com/reference/criar-token-de-api)                                | `v1/{account_id}/api_tokens`        |
| [Listar API Tokens](https://dev.iugu.com/reference/listar-api-tokens)                               | `v1/{account_id}/api_tokens`        |

<br />

## Como assinar suas requisições?

Consulte a documentação [Autenticação com Assinatura RSA](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#autentica%C3%A7%C3%A3o-com-assinatura-rsa). Nela está presente um [Webinar](https://youtu.be/oY9-8cVQzvo) e também uma [Recipe](https://dev.iugu.com/recipes/rsa-assinatura-rsa) de como implantar esta solução em seu `script`.