> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluggoucash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar suas requisições na API da Pluggou

## Visão geral

A API da Pluggou utiliza um sistema de autenticação baseado em **chaves públicas e secretas** para garantir a segurança de todas as operações. Cada requisição à API deve incluir ambas as chaves nos headers HTTP, permitindo que a plataforma identifique sua conta e valide as permissões de acesso.

Esse modelo de autenticação por par de chaves oferece diversas vantagens:

* **Segurança reforçada** — a combinação de chave pública e secreta garante que apenas aplicações autorizadas possam acessar sua conta
* **Controle granular** — você pode criar múltiplas credenciais com permissões específicas para diferentes finalidades
* **Rastreabilidade** — cada par de chaves pode ser identificado individualmente, facilitando auditoria e monitoramento

***

## Headers de autenticação

Todas as requisições devem incluir os seguintes headers obrigatórios:

| Header         | Descrição                         | Exemplo                   |
| -------------- | --------------------------------- | ------------------------- |
| `Content-Type` | Tipo do conteúdo da requisição    | `application/json`        |
| `X-Public-Key` | Sua chave pública de acesso à API | `pk_live_abc123def456...` |
| `X-Secret-Key` | Sua chave secreta de acesso à API | `sk_live_xyz789ghi012...` |

### Exemplo de requisição autenticada

```bash theme={null}
curl -X POST https://api.pluggoutech.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_live_abc123def456..." \
  -H "X-Secret-Key: sk_live_xyz789ghi012..."
```

<Warning>
  Nunca compartilhe sua **chave secreta** (`X-Secret-Key`) publicamente, em repositórios de código ou em código frontend. Trate suas credenciais com o mesmo cuidado que uma senha. Caso suspeite que suas chaves foram comprometidas, revogue-as imediatamente e gere novas credenciais no Dashboard.
</Warning>

***

## Tipos de chaves

A Pluggou permite que você crie múltiplas credenciais com diferentes níveis de permissão. Isso possibilita um controle mais fino sobre o que cada integração pode fazer na plataforma.

| Tipo de chave       | Permissão                                                   | Uso recomendado                                 |
| ------------------- | ----------------------------------------------------------- | ----------------------------------------------- |
| **Apenas entradas** | Permite apenas operações de recebimento (gerar transações)  | Sistemas de checkout e cobrança                 |
| **Apenas saídas**   | Permite apenas operações de saída (transferências e saques) | Sistemas financeiros e de pagamento a terceiros |
| **Ambas**           | Permite operações de entrada e saída                        | Integrações completas com controle total        |

<Tip>
  Recomendamos criar chaves com as **permissões mínimas necessárias** para cada integração. Por exemplo, se um sistema só precisa gerar cobranças, utilize uma chave do tipo "Apenas entradas". Isso reduz o risco em caso de comprometimento da credencial.
</Tip>

***

## Como gerar suas credenciais

Siga o passo a passo abaixo para criar suas chaves de API diretamente no Dashboard da Pluggou:

<Steps>
  <Step title="Acesse o Dashboard">
    Faça login na sua conta em [pluggoucash.com](https://pluggoucash.com) e navegue até a seção de gerenciamento de APIs.

    Você também pode acessar diretamente pelo link: [pluggoucash.com/dashboard/apis](https://pluggoucash.com/dashboard/apis)
  </Step>

  <Step title="Acesse a aba de API">
    No menu lateral do Dashboard, clique na aba **API** para acessar o gerenciamento de credenciais.
  </Step>

  <Step title="Crie uma nova chave">
    Clique no botão **Criar nova Chave API**. Um formulário será exibido solicitando as informações da nova credencial.
  </Step>

  <Step title="Preencha as informações">
    Informe os seguintes dados:

    * **Nome da chave** — um nome descritivo para identificar a credencial (ex: "Integração Loja Virtual", "Sistema Financeiro")
    * **Tipo da chave** — selecione a permissão desejada: apenas entradas, apenas saídas ou ambas

    Após preencher, confirme a criação.
  </Step>

  <Step title="Copie suas credenciais">
    Após a criação, suas chaves pública (`X-Public-Key`) e secreta (`X-Secret-Key`) serão exibidas na tela.
  </Step>
</Steps>

***

## Gerenciando suas credenciais

Você pode criar quantas chaves precisar para sua operação. No painel de [gerenciamento de APIs](https://pluggoucash.com/dashboard/apis), é possível:

* **Visualizar** todas as chaves ativas da sua conta
* **Identificar** cada chave pelo nome atribuído na criação
* **Revogar** chaves que não são mais necessárias ou que possam ter sido comprometidas

<Info>
  Manter um controle organizado das suas credenciais é uma boa prática de segurança. Revogue chaves que não estão mais em uso e renomeie-as de forma descritiva para facilitar a gestão.
</Info>

***

## Erros de autenticação

Caso as credenciais enviadas sejam inválidas, ausentes ou não tenham permissão para a operação solicitada, a API retornará um erro com o código HTTP apropriado:

| Código | Situação                                   |
| ------ | ------------------------------------------ |
| `401`  | Chaves ausentes ou inválidas na requisição |
| `403`  | Chave não possui permissão para a operação |

```json theme={null}
{
    "error": "Credenciais inválidas",
    "message": "Chave não encontrada ou inativa"
}
```

## Precisa de ajuda?

Se tiver dificuldades para gerar ou configurar suas credenciais, nosso time de suporte está disponível para ajudar.

<Card title="WhatsApp de Suporte" icon="whatsapp" href="https://wa.me/+555181791451?text=Ola%2C%20estou%20integrando%20a%20Pluggou%20em%20meu%20sistema%20e%20estou%20com%20duvidas%2C%20poderia%20me%20auxiliar%3F">
  Fale diretamente com nosso time técnico pelo WhatsApp para tirar dúvidas sobre autenticação e credenciais.
</Card>