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

# Autenticação

> Como autenticar suas requisições na API Nixfy Gateway

Todas as requisições à API pública do Nixfy Gateway requerem autenticação via **API Keys**.

## API Keys

As API Keys são compostas por dois componentes:

1. **Chave Pública (Public Key)**: Identifica sua conta
2. **Chave Privada (Private Key)**: Autentica suas requisições

### Obtendo suas API Keys

<Steps>
  <Step title="Acesse o Dashboard">
    Acesse o [Dashboard Nixfy Gateway](https://app.nixfypagamentos.com) e faça login na sua conta.
  </Step>

  <Step title="Navegue até API Keys">
    No menu lateral, navegue até **Integrações** → **Credenciais de API**.
  </Step>

  <Step title="Gere um novo par de chaves">
    Clique em **Gerar Nova Chave** e confirme a ação.
  </Step>

  <Step title="Guarde suas chaves com segurança">
    <Warning>
      **Importante**: Guarde a chave privada com segurança, ela não será exibida novamente após a geração.
    </Warning>

    <Tip>
      Recomendamos salvar as chaves em um gerenciador de senhas ou variáveis de ambiente seguras.
    </Tip>
  </Step>
</Steps>

## Como Usar

Inclua as chaves de API nos cabeçalhos de todas as requisições:

<ParamField header="X-Api-Public-Key" type="string" required>
  Sua chave pública da API (formato: `pk_...`)
</ParamField>

<ParamField header="X-Api-Private-Key" type="string" required>
  Sua chave privada da API (formato: `sk_...`)
</ParamField>

### Exemplos de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.nixfypagamentos.com/api/transactions/123 \
    -H "X-Api-Public-Key: sua_chave_publica_aqui" \
    -H "X-Api-Private-Key: sua_chave_privada_aqui"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.nixfypagamentos.com/api/transactions/123', {
    method: 'GET',
    headers: {
      'X-Api-Public-Key': 'sua_chave_publica_aqui',
      'X-Api-Private-Key': 'sua_chave_privada_aqui',
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-Api-Public-Key': 'sua_chave_publica_aqui',
      'X-Api-Private-Key': 'sua_chave_privada_aqui',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://api.nixfypagamentos.com/api/transactions/123',
      headers=headers
  )
  ```
</CodeGroup>

## Restrição por IP

Além das chaves, você pode limitar **de quais endereços IP** sua API key funciona. É a defesa que continua valendo mesmo se a chave privada vazar: uma requisição com as chaves corretas, mas vinda de um IP fora da lista, é recusada.

<Info>
  A lista começa **vazia**, e lista vazia significa **sem restrição** — sua chave funciona de qualquer origem. A proteção só passa a valer depois que você cadastra o primeiro IP.
</Info>

### Como funciona

<ParamField path="Correspondência" type="exata">
  O IP de origem precisa ser **idêntico** a um da lista. Não há suporte a faixas CIDR (`192.168.0.0/24`) nem curingas — cadastre cada endereço individualmente.
</ParamField>

<ParamField path="Formatos aceitos" type="IPv4 e IPv6">
  Ambos são aceitos. Endereços IPv4 mapeados em IPv6 (`::ffff:200.150.100.50`) são normalizados para a forma IPv4, então cadastrar `200.150.100.50` cobre as duas representações.
</ParamField>

<ParamField path="Limite" type="20 endereços">
  Cada conta pode cadastrar até 20 IPs.
</ParamField>

<Warning>
  A restrição vale **apenas para requisições autenticadas por API key**. O acesso ao painel pela sua sessão de login não passa por essa verificação — trancar a API não tranca o dashboard.
</Warning>

### Configurando

No painel, vá em **Integrações** → **Credenciais de API** e edite a lista de IPs autorizados. A mesma operação está disponível na rota abaixo, autenticada pela sessão do painel (não pela API key):

Para **remover** a restrição e voltar a aceitar qualquer origem, envie uma lista vazia:

Um endereço malformado faz a requisição inteira falhar, sem alterar nada — a resposta diz qual valor foi recusado:

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "message": "IP inválido: 999.1.1.1",
    "code": "INVALID_IP"
  }
  ```
</ResponseExample>

### Quando um IP é bloqueado

Requisições vindas de fora da lista recebem **403** com o código `IP_NOT_ALLOWED`:

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "message": "Requisição recusada: o IP de origem não está na lista de IPs autorizados desta chave.",
    "code": "IP_NOT_ALLOWED"
  }
  ```
</ResponseExample>

<Tip>
  Se você usa servidores com IP dinâmico, ou um provedor que roteia a saída por vários endereços, cadastre todos os IPs de saída possíveis — ou deixe a lista vazia e proteja a chave por outros meios. Uma lista incompleta derruba requisições legítimas em produção.
</Tip>

## Segurança

<Warning>
  **Importante**: Nunca exponha suas chaves de API em código frontend ou repositórios públicos. Sempre use variáveis de ambiente ou serviços de gerenciamento de segredos.
</Warning>

### Boas Práticas

* ✅ Armazene as chaves em variáveis de ambiente
* ✅ Use serviços de gerenciamento de segredos (AWS Secrets Manager, HashiCorp Vault, etc.)
* ✅ Rotacione suas chaves regularmente
* ✅ Revogue chaves comprometidas imediatamente
* ❌ Nunca commite chaves em repositórios Git
* ❌ Nunca exponha chaves em código frontend

## Erros de Autenticação

### 401 Unauthorized

Retornado quando as chaves de API são inválidas ou ausentes:

<ResponseExample>
  ```json Error - 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Chaves de API inválidas ou ausentes"
    }
  }
  ```
</ResponseExample>

### 403 Forbidden

Retornado quando a operação não é permitida para sua conta:

<ResponseExample>
  ```json Error - 403 Forbidden theme={null}
  {
    "success": false,
    "error": {
      "code": "FORBIDDEN",
      "message": "Operação não permitida para esta conta"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.