---
updatedAt: 2026-07-28T20:16:41.000Z
agentTools:
  projectIndex: https://dev.iugu.com/llms.txt
---

# 🔒 Autenticação

Métodos de autenticação na iugu

<Callout icon="📘" theme="info">
  ### O que você irá aprender com esse artigo?

  - Tipos de autenticação
  - Diferenças entre os tokens
  - Criando suas chaves de API via painel
  - Como criar os tokens via API
  - Como utilizar o `live_token` e o `test_token`
  - Assinatura de Requisições (RSA)
</Callout>

# Tipos de autenticação

A autenticação na iugu é realizada por meio de uma chave de API, que permite ao sistema identificar a sua conta e conceder as permissões necessárias para a comunicação com a iugu em nome da conta associada.

Existem três métodos de autenticação disponíveis, sendo o mais recomendado o uso do `HTTP` `Basic Auth`. A segunda opção é a autenticação por `Bearer` `Authentication`. A terceira alternativa é enviar o API Token como um parâmetro denominado `api_token`.

***

# `live_token`, `test_token`, `user_token` e `master_token`

1. `live_token`: utilize-o para ações em ambiente produção.
2. `test_token`: utilize-o para ações em ambiente de teste (homologação/sandbox).
3. `master_token`: utilize-o para Criar, Listar API Tokens e/ou Remover API Token.
4. `user_token`: utilize-o para requisições à endpoints que requiram uma autenticação a nível *usuário*.

### Rotas que utilizam `user_token` ou ` master_token`

`master_token`

| Referência da API                                                        | Endpoint                          |
| :----------------------------------------------------------------------- | :-------------------------------- |
| [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}` |

`user_token`

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

***

## Como ter acesso ao `user_token`?

* No retorno `200 OK` do endpoint [Criar Subconta](https://dev.iugu.com/reference/criar-subconta) — `v1/marketplace/create_account`.

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

  - Os endpoints Criar Subconta e Listar API Tokens das subcontas são requisitadas, exclusivamente, pela Conta Mestre.
  - Utilize o `master_token`
</Callout>

***

# Criar `api_token`

Há duas formas de criar um `api_token`:

1. Via <Glossary>Alia</Glossary>
2. Via API

## Alia

1. Acesse [alia.iugu.com](https://alia.iugu.com) > Configurações
2. Integrações API > Novo
3. Escolha entre Teste, Produção ou Mestre\*.
   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. Dê uma descrição. Por exemplo: "Minha chave API"
5. Clique em **Salvar**.

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

  - Este `api_token` ficará visível por apenas 1h. Após isso, será **censurado**.
  - A criação de `api_tokens` dependem de uma aprovação enviada para os Administradores da Conta.
</Callout>

## API

Utilize o endpoint [Criar API Token](https://dev.iugu.com/reference/criar-token-de-api) — `v1/{account_id}/api_tokens`.

### Request e Response exemplo

```shell Request
curl --request POST \
     --url 'https://api.iugu.com/v1/27016E1AD888499A98994E781B6C3762/api_tokens?api_token=your-api_token' \
     --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": "8D3EA0B0F546405B880F1BAC7B2CA5A7",
  "token": "ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0",
  "api_type": "LIVE",
  "description": "Meu token de produção",
  "created_at": "2025-03-12T15:00:22-03:00",
  "status": "active"
}
```

## Dica de segurança 🔐

Recomendamos a atualização da sua chave de API a cada 30 dias. Manter a chave atualizada é fundamental para evitar seu uso indevido em caso de vazamento de informações.

Não se esqueça de que sua chave de API funciona como uma senha, sendo ela responsável por autorizar suas transações de forma automática e autenticada.

***

# Como utilizar o `live_token` e o `test_token`

## HTTP Basic Auth

Para gerar o header de autenticação HTTP Basic da request, deve-se seguir os seguintes passos:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:<br />**Base64 dessa chave:** NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada<br />Exemplo: --header 'Authorization: Basic NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

**Modelo de request**

```curl
curl --location --request GET 'https://api.iugu.com/v1/customers' 
--header 'Accept: application/json' 
--header 'Content-Type: application/json' 
--header 'Authorization: Basic {apitoken in base64}' 
--header 'Cookie: __cfruid=df598e45cd90947e522e12ec895a84f7059cacbc-1627922464' 
--data-raw ''
```

**Parâmetro api\_token**

As requests permitem o envio de um parâmetro chamado **api\_token**, onde pode ser enviado o API Token gerado anteriormente em vez de utilizar o HTTP Basic Auth.

## Bearer Authentication

Há a possibilidade também de utilizar a autenticação Bearer.

Para gerar o header de autenticação HTTP Bearer, deve-se seguir os seguintes passos:

1. Ter a chave API, seja de teste ou de Produção

2. Codificar a chave API, junto com o caracter “:” no final da chave, para o formato Base64. Exemplo: 5AA555555555555555555555555555555CC55555555555555555555555555DD5:<br />**Base64 dessa chave:** NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

3. No header, inserir o campo de “Authorization”, seguido com o valor que é a chave API codificada<br />Exemplo: --header 'Authorization: Bearer NUFBNTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1Q0M1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NTU1NURENTo=

**Modelo de Request**

```curl
curl --location --request GET 'https://api.iugu.com/v1/customers' \ 
--header 'Accept: application/json' 
--header 'Content-Type: application/json' 
--header 'Authorization: Basic {apitoken in base64}' 
--header 'Cookie: __cfruid= 95dfe99ff2d3d94d649675cf8cb7491b4bda25b7-1641564409' \ 
--data-raw ''
```

***

# Autenticação com Assinatura RSA

## O que é Assinatura RSA?

Uma Assinatura RSA em APIs é um método de criptografia que utiliza o algoritmo RSA para garantir a autenticidade e a integridade das mensagens trocadas entre um cliente e um servidor. Ela envolve a criação de uma assinatura digital usando uma chave privada, que pode ser verificada por qualquer pessoa com a chave pública correspondente. Isso assegura que a mensagem foi enviada por uma fonte confiável e que não foi alterada durante a transmissão.

***

# Endpoints obrigatórios

Os endpoints que têm como características <Glossary>Cash Out</Glossary>, criação de conta e API Tokens, por exemplo, requerem essa autenticação. São eles:<br />

| 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 />

# Prefere um vídeo ensinando como faz?

Assista nosso Webinar conduzido por um dos nossos Engenheiros:

<Embed title="" typeOfEmbed="youtube" url="https://www.youtube.com/watch?v=oY9-8cVQzvo" href="https://www.youtube.com/watch?v=oY9-8cVQzvo" html="%3Ciframe%20class%3D'embedly-embed'%20src%3D'%2F%2Fcdn.embedly.com%2Fwidgets%2Fmedia.html%3Fsrc%3Dhttps%3A%2F%2Fwww.youtube.com%2Fembed%2FoY9-8cVQzvo%3Ffeature%3Doembed%26display_name%3DYouTube%26url%3Dhttps%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DoY9-8cVQzvo%26image%3Dhttps%3A%2F%2Fi.ytimg.com%2Fvi%2FoY9-8cVQzvo%2Fhqdefault.jpg%26key%3D7788cb384c9f4d5dbbdbeffd9fe4b92f%26type%3Dtext%2Fhtml%26schema%3Dyoutube'%20width%3D'854'%20height%3D'480'%20scrolling%3D'no'%20title%3D'YouTube%20embed'%20frameborder%3D'0'%20allow%3D'autoplay%3B%20fullscreen%3B%20encrypted-media%3B%20picture-in-picture%3B'%20allowfullscreen%3D'true'%3E%3C%2Fiframe%3E" />

***

# Que tal uma Recipe?🧪

Aqui está uma **sugestão** de como o seu script pode ser desenvolvido:

### `Ruby on Rails`

<Recipe slug="rsa-ruby-assinatura-rsa" title="[RSA] [Ruby] Assinatura RSA" />

### `Node.js`

<Recipe slug="rsa-nodejs-assinatura-rsa" title="[RSA] [Node.js] Assinatura RSA" />

### `PHP`

<Recipe slug="rsa-php-assinatura-rsa" title="[RSA] [PHP] Assinatura RSA" />

### `Python`

<Recipe slug="rsa-python-assinatura-rsa-1" title="[RSA] [Python] Assinatura RSA" />

### `Java`

<Recipe slug="rsa-java-assinatura-rsa" title="[RSA] [Java] Assinatura RSA" />

***

# Antes de começar ⚠️

Alguns pontos importantes antes de começar:

1. É possível apenas em **produção** (`live_mode`)
2. É permitido múltiplos API Tokens LIVE com Assinatura RSA, graças ao novo parâmetro `X-Signature-Token-Id.`
3. Necessário ter acesso ao <Glossary>Alia</Glossary> para a etapa de criação do `api_token`.
   1. Não é possível utilizar o endpoint [Criar API Token](https://dev.iugu.com/reference/criar-token-de-api) — `v1/{account_id}/api_tokens` como alternativa, pois este também requer RSA.
4. Este processo exige a utilização de [OpenSSL](https://www.openssl.org/).
5. Crie uma pasta que armazenará os arquivos do OpenSSL.
6. Navegue até esta pasta utilizando o cmd

Após estas etapas, continue com este artigo.

***

# Usuários Linux

Comandos de copy serão utilizados neste passo a passo. Certifique-se de que o `xclip` ou `xsel` está instalado no seu sistema. Você pode instalar com:

```text Unix
$ sudo apt-get install xclip
```

ou

```text Unix
$ sudo apt-get install xsel
```

***

# Fluxo Whitelabel

Para estruturas de Marketplace (subcontas), é possível seguir as etapas deste guia e refletir para as subcontas atreladas à Mestre, descartando a necessidade de fazê-la uma a uma.

Para isso, siga as etapas de [1](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#1-gerar-chave-privada) a [4](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#4-colar-chave-p%C3%BAblica-no-painel) na **Conta Mestre** e, nas etapas de [5](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#5-assinar-e-enviar-requisi%C3%A7%C3%A3o) a [12](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#12-enviar-requisi%C3%A7%C3%A3o), e onde for solicitado o "`api_token` criptografado", insira o `live_api_token` da subconta, por mais que ele **não** seja criptografado.

### Ilustração do Fluxo

<Image src="https://files.readme.io/ee52799-sequence-diagram-rsa-whitelabel.png" alt="Assinatura RSA Whitelabel" align="center" caption="Assinatura RSA Whitelabel" />

## O que precisará ter?

* Uma subconta com um `live_api_token`
* A Conta Mestre desta Subconta com um `api_token` criptografado.

Continue com este artigo.

***

# 1. Gerar chave privada

No `cmd`, insira este comando:

```Text Bash
$ openssl genrsa -out private.pem 2048
```

# 2. Gerar chave pública

Ainda no `cmd`, insira o comando abaixo para gerar a chave pública **a partir** da chave privada

```Text Bash
$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```

# 3. Copiar a chave pública

Copie para o clipboard a chave pública gerada:

### Windows

```Text Bash
$ clip < public.pem
```

### macOS

```Text Bash
$ pbcopy < public.pem
```

### Linux (xclip)

```text Unix
xclip -selection clipboard < public.pem
```

### Linux (xsel)

```text Unix
$ xsel --clipboard < public.pem
```

# 4. Colar chave pública no painel

1. Acesse [alia.iugu.com](https://alia.iugu.com)
2. Configurações > Integrações via API
3. Clique em Novo > e, em Tipo, selecione **Produção**
4. Dê uma descrição para esta chave (exemplo: Minha chave RSA)
5. Abaixo de descrição, cole a chave pública mantendo os cabeçalhos `----BEGIN PUBLIC KEY----` e `----END PUBLIC KEY----`
6. Clique em **Salvar**.

Esta chave será identificada como **Chave criptografada**.

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

  - A criação de `api_tokens` dependem de uma aprovação enviada para os Administradores da Conta.
  - Guarde o `api_token` gerado em um lugar seguro
</Callout>

***

# Body = `raw`

Assine o corpo da requisição de forma bruta (raw), sem qualquer tratamento ou parse. O payload assinado deve ser idêntico ao enviado na requisição. A assinatura gerada deve ser criptografada em base64 e incluída na requisição.

O restante permanece inalterado: o corpo da requisição deve conter o `api_token` e todos os campos necessários, **sem qualquer alteração** no processo usual.

<Callout icon="❗️" theme="error">
  ### Quebra de Linhas

  Ao montar o arquivo no Windows, não utilize editores **no terminal**, como Vim, Nano, etc. Qualquer espaço, aspas, quebra de linha, **invalidará** a requisição.

  Recomendamos a utilização de editores de texto como **Notepad++**, **VSCode** ou, até mesmo, o próprio Bloco de Notas, que permitem a visualização das quebras das delinha CR LF, LF e CR, que variam entre Sistemas Operacionais.
</Callout>

***

# 5. Assinar e enviar requisição

Com a chave criptografada criada em sua conta ([etapa 1](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#1-gerar-chave-privada) ao [4](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#4-colar-chave-p%C3%BAblica-no-painel)), continue com este artigo para a **Assinatura da Requisição**.

## Atenção ⚠️

As próximas etapas servem para **simular** os processos técnicos e o seu resultado. A forma de implantá-la fica à critério do cliente/seller.

As etapas de [5](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#5-assinar-e-enviar-requisi%C3%A7%C3%A3o) ao [12](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#12-enviar-requisi%C3%A7%C3%A3o) devem ser realizadas para **todas as requisições**, sem exceção.

### Timestamp padrão `ISO8061` e UTC

O timestamp segue os padrões `ISO8061`. O UTC deve ser **o mesmo** do servidor que esta solução será hospedada.

Utilize os comandos abaixo para gerar um timestamp nos padrões `ISO8061`:

#### macOS

```text bash
date +"%Y-%m-%dT%H:%M:%S%Z:00"
```

#### Linux

```text text
date +"%Y-%m-%dT%H:%M:%S%:z"
```

<Callout icon="🚧" theme="warn">
  ### Tolerância de 5 minutos

  O timestamp inserido no documento tem uma tolerância de até 5 minutos. Por exemplo: 2024-06-15T12:**55**:00-03:00, só é possível enviar a requisição até 12:59:59. Se exceder, retornará `Invalid Signature`
</Callout>

## 5.1 Criar arquivo `.txt`

1. Crie um arquivo `.txt` com nome 'documento' em sua pasta (etapa 5 de [Atenção ⚠️](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#antes-de-come%C3%A7ar-%EF%B8%8F))
2. Para cada endpoint, escreva o `body` no 'documento', seguindo, exatamente, os padrões a seguir:

| Linha | Conteúdo                            | Exemplo                                                                                       |
| :---- | :---------------------------------- | :-------------------------------------------------------------------------------------------- |
| 1     | Método\|endpoint                    | POST\|/v1/signature/validate                                                                  |
| 2     | api\_tokencriptografado\|timestamp  | 1AB1CD2EF1BC9DE0165FC37268331E1A4A0D8FCF90E2C42AB4100CBDB86E5136\|2024-06-15T12:21:29-03:00   |
| 3     | `body` da requisição **sem espaço** | \{"name":"Nome da Subconta","splits":\[\{"recipient\_account\_id":"account\_id","cents":20}]} |

### Importante :warning:

A linha 3 **não deve conter nenhum espaço**, a não ser que seja o valor de um parâmetro, por exemplo "Nome da Subconta". Este pode conter espaços, pois é um valor e não interferirá.

O resultado do exemplo acima é:

```text documento.txt
POST|/v1/signature/validate
1AB1CD2EF1BC9DE0165FC37268331E1A4A0D8FCF90E2C42AB4100CBDB86E5136|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}
```

### Observações — [Whitelabel](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#fluxo-whitelabel)

* **Na linha 2:** Informe o `live_pi_token` da subconta.

### Exemplos de `documento.txt` de cada endpoint

Os scripts abaixo são exemplos de como o seu documento deve ser escrito para ser assinado:

### [Criar API Token](https://dev.iugu.com/reference/criar-token-de-api) — `POST` `/v1/{account_id}/api_tokens`

```text text
POST|/v1/12345A1BC666499D98994A781E6C3762/api_tokens
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2025-03-12T14:58:01-03:00
{"api_type":"LIVE","description":"Meu Token de produção"}
```

### [Transferir Valor](https://dev.iugu.com/reference/transferir-valor) — `POST` `v1/transfers`

```text text
POST|/v1/transfers
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"receiver_id":"id-da-conta","amount_cents":100}
```

### [Transferência para Terceiros](https://dev.iugu.com/reference/transfer%C3%AAncia-para-terceiros-1) — `POST` `v1/transfers_requests`

```text text
POST|/v1/transfer_requests
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"receiver":{"pix":{"type":"email","key":"iugu@iugu.com"},"name":"Nome","cpf_cnpj":"113.436.750-30"},"transfer_type":"pix","amount_cents":100}
```

### [Pedido de Saque/Transferências Próprias](https://dev.iugu.com/reference/pedido-de-saque) — `POST` `v1/accounts/{id}/request_withdraw`

```text text
POST|/v1/accounts/id-da-subconta/request_withdraw
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"amount":10}
```

### [Validate Signature](https://dev.iugu.com/reference/validate-signature) — `POST` `v1/signature/validate`

```text text
POST|/v1/signature/validate
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"RAW_BODY":"string"}
```

### [Criar Subconta](https://dev.iugu.com/reference/criar-subconta) — `POST` `v1/marketplace/create_account`

```text
POST|/v1/marketplace/create_account
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"name":"Nome da Subconta","splits":[{"recipient_account_id":"account_id","cents":20}]}
```

### [Configurar Conta](https://dev.iugu.com/reference/configurar-conta) — `POST` `v1/accounts/configuration`

```text
POST|/v1/accounts/configuration
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"auto_withdraw":true,"auto_advance":false}
```

### [Adicionar domicílio bancário](https://dev.iugu.com/reference/adicionar-domicilio-bancario) — `POST` `/v1/bank_verification`

```text
POST|/v1/bank_verification
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"agency":"0000","account":"000000","account_type":"cc","bank":"001"}
```

### [Criar Pedido de Pagamento](https://dev.iugu.com/reference/criar-pedido-de-pagamento) — `POST` `v1/payment_requests`

```text text
POST|/v1/payment_requests
ABC123DEF45D4B9E27C8126BE74850A4366492313823D1811114769BD0D5F0B0|2024-06-15T12:21:29-03:00
{"barcode":"846100000013310502962023004200030007003752691117","document_amount_cents":10,"amount_cents":10}
```

## 5.2 Salvar arquivo

Após informações inseridas, salve este arquivo e **não altere-o mais**.

# 6. Assinar `documento.txt` usando Chave privada

No `cmd`, insira o seguinte comando:

```text text
openssl dgst -sha256 -sign private.pem -out sign.sha256 documento.txt
```

# 7. Transformar em `base64`

Insira o comando abaixo para transformar (encode) para `base64` o conteúdo do arquivo `sign.sha256` de sua pasta:

```text text
openssl base64 -A -in sign.sha256 -out sign.sha256.base64
```

<Callout icon="📘" theme="info">
  ### `sign.sha256.base64`

  Após executá-lo, **cria-se um novo arquivo** de nome `sign.sha256.base64` na mesma pasta.
</Callout>

# 8. Copiar conteúdo `sign.sha256.base64`

Insira o comando para copiar para o clipboard o conteúdo que será utilizado no header — `Signature` — da requisição

#### Windows

```Text Bash
clip < sign.sha256.base64
```

#### macOS

```Text Bash
$ pbcopy < sign.sha256.base64
```

#### Linux (xclip)

```text Unix
xclip -selection clipboard < sign.sha256.base64
```

#### Linux (xsel)

```text Unix
$ xsel --clipboard < sign.sha256.base64
```

# 9. Preparar o `URL`

Utilize um dos endpoints (de acordo com a [etapa 5.1](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#51-criar-arquivo-txt)) que deseja e atente-se às seguintes informações:

Neste exemplo, foi escolhido o endpoint de [Transferência para Terceiros](https://dev.iugu.com/reference/transfer%C3%AAncia-para-terceiros-1) — `v1/transfer_requests`, então, preencha de acordo com a sua requisição:

```http
https://api.iugu.com/v1/transfer_requests?api_token=api_tokencriptografado
```

# 10. Copiar o `body` do `documento.txt`

Copie apenas a terceira linha do `documento.txt`:

```json
{"receiver_id":"id-da-conta","amount_cents":100,"api_token":"api_tokencriptografado"}
```

### Como o header deve ficar?

Preencha os parâmetros do header no padrão 'parâmetro=valor' de acordo com estas instruções:

| Parâmetro                        | O que preencher                                                                                                                                       | Valor (exemplo)                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| <p><code>Signature</code></p>    | <p>o conteúdo copiado da<br /><a href="https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#8-copiar-conte%C3%BAdo-signsha256base64">etapa 8</a></p> | <p><code>signature=sequência-de-caracteres</code></p> |
| <p><code>Request-Time</code></p> | <p>Timestamp gerado no momento<br />da assinatura</p>                                                                                                 | <p><code>2024-06-15T12:21:29-03:00</code></p>         |
| <p><code>Accept</code></p>       | <p>o tipo de resposta esperada do servidor</p>                                                                                                        | <p><code>application/json</code></p>                  |
| <p><code>Content-Type</code></p> | <p>o formato dos dados enviados<br />no body da requisição</p>                                                                                        | <p><code>application/json</code></p>                  |

# 11. Colar o conteúdo no `body`

Com o conteúdo do body copiado ([etapa 10](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#10-copiar-o-body-do-documentotxt)), cole no corpo da requisição.

<Callout icon="🚧" theme="warn">
  ### Verifique se houve alteração

  Alguns editores de texto formatam os arquivos por padrão e isso poderá invalidar a assinatura (`Invalid Signature`). Se alterado, utilize o Bloco de Notas, VSCode ou Notepad++.
</Callout>

# 12. Enviar requisição

Certifique-se de ter seguido estritamente todos os passos deste guia e, por fim, requisite o endpoint escolhido.

***

# Verificar se assinatura é válida (opcional)

Utilize o endpoint [Validate Signature](https://dev.iugu.com/reference/validate-signature) — `v1/signature/validate` para verificar se a assinatura gerada ([etapa 7](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#7-transformar-em-base64) e [8](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#8-copiar-conte%C3%BAdo-signsha256base64)) é válida. Ou seja, esta rota **não** torna uma assinatura válida, apenas a **verifica**.

Este endpoint segue a mesma lógica das etapas [5](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#5-assinar-e-enviar-requisi%C3%A7%C3%A3o) até [12](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#12-enviar-requisi%C3%A7%C3%A3o), então, siga-os para requisitá-lo.

### Request e Response exemplo

```curl Request
curl --request POST \
     --url 'https://api.iugu.com/v1/signature/validate?api_token=api_tokencriptografado' \
     --header 'Request-Time: 2024-06-15T12:21:29-03:00' \
     --header 'Signature: signature=sequência-de-caracteres' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{"RAW_BODY": "Validando a integração"}'
```
```json Response
{
  "message": "Signature check successful",
  "request_body": "{\n  'api_token':'<api_token-criptografado>',\n  'message':'anything'\n}",
  "status": "ok"
}
```

## `Signature check successful`

O retorno `"message": "Signature check successful"` serve **apenas** para validar que o seu script seguiu a lógica correta.

## Importante :warning:

Este é o único endpoint que o [Fluxo Whitelabel](https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#fluxo-whitelabel) **não é compatível**.

***

# Erros

Os erros de criptografia são sucintos por, justamente, serem criptografados. Apesar disso, há erros que têm uma explicação. Veja-os abaixo:

<Table>
  <thead>
    <tr>
      <th>
        Erro
      </th>

      <th>
        Motivo(s)/hipótese(s)
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p><code>Public Key Not Found</code></p>
      </td>

      <td>
        <ul>
          <li><p>O <code>documento.txt</code> não foi criado no mesmo servidor<br />que a aplicação está hospedada.</p></li>
          <li><p>Chave criptografada na Conta Mestre pode ter sido<br />criada de forma incorreta.</p></li>
          <li><p>Se a requisição for com api\_token de uma subconta,<br />é obrigatório que tenha sido criado a chave pública na<br />Conta Mestre</p></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <p><code>Invalid Elepsed Time</code></p>
      </td>

      <td>
        <ul>
          <li><p>Data do <code>Request-Time </code>está diferente da data enviada<br />no arquivo.</p></li>
          <li><p>Ultrapassou os 5 minutos (<a href="https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#timestamp-padr%C3%A3o-iso8061-e-utc">saiba mais</a>)</p></li>
          <li><p>O minuto do servidor está divergente do mundial. Ao criar<br />o timestamp em <code>ISO8061</code>, automaticamente, é convertido para GMT+03:00.<br />Se trata de um padrão mundial alterar apenas o horário.</p></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <p><code>Invalid Signature</code></p>
      </td>

      <td>
        <ul>
          <li>O <code>documento.txt</code> está diferente da requisição</li>
          <li>Há uma quebra de linha (manual ou durante o processo)</li>
          <li>No código, a quebra de linha está como <code>/r/n</code> (deve ser <code>\r\n</code>)</li>
          <li>Para cada requisição, deve-se criar um <strong>novo</strong> <code>documento.txt</code> com os dados<br />da requisição em questão</li>
          <li>Algumas aplicações quebram o <code>documento.txt</code> (<a href="https://dev.iugu.com/reference/autentica%C3%A7%C3%A3o#body--raw">saiba mais</a>)</li>
        </ul>
      </td>
    </tr>
  </tbody>
</Table>

***

# Referências técnicas

Algumas referências para fins de conhecimento:

* [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication)
* [Manual Base64](https://pt.wikipedia.org/wiki/Base64)
* [Bearer Authentication](https://learning.postman.com/docs/sending-requests/authorization/authorization/#bearer-token)
* [Padrão ISO 8601 para tempo (inglês)](https://www.iso.org/iso-8601-date-and-time-format.html)
* [Gerar chave RSA pelo terminal (inglês)](https://rietta.com/blog/openssl-generating-rsa-key-from-command)

<br />