# Autenticacao

A API Monetarie NPC utiliza autenticacao via **API Key** para proteger todos os endpoints. Cada requisicao deve incluir sua chave no cabecalho HTTP.

## Como Funciona

Todas as requisicoes a API devem incluir o cabecalho `X-API-Key` com sua chave de acesso:

```bash
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

## Formato das API Keys

As API Keys seguem um formato padronizado que identifica o ambiente:

| Prefixo      | Ambiente   | Exemplo                          | Uso                              |
|--------------|------------|----------------------------------|----------------------------------|
| `pk_test_`   | Sandbox    | `pk_test_abc123def456ghi789`     | Testes e homologacao             |
| `pk_live_`   | Producao   | `pk_live_xyz789abc123def456`     | Ambiente produtivo               |

::: info Identificacao do Ambiente
O prefixo da sua API Key determina automaticamente qual ambiente sera utilizado. Nao e possivel usar uma chave de sandbox em producao e vice-versa.
:::

## Exemplo Completo

::: code-group

```bash [cURL]
curl -X POST "https://sandbox.monetarie_npc.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_test_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 15000,
    "vencimento": "2026-03-15",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901"
    }
  }'
```

```javascript [JavaScript]
const response = await fetch(
  "https://sandbox.monetarie_npc.com.br/api/v1/central/boletos",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_test_abc123def456ghi789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      valor: 15000,
      vencimento: "2026-03-15",
      pagador: {
        nome: "Joao Silva",
        documento: "12345678901"
      }
    }),
  }
);

const data = await response.json();
```

```python [Python]
import requests

url = "https://sandbox.monetarie_npc.com.br/api/v1/central/boletos"
headers = {
    "X-API-Key": "pk_test_abc123def456ghi789",
    "Content-Type": "application/json"
}
payload = {
    "valor": 15000,
    "vencimento": "2026-03-15",
    "pagador": {
        "nome": "Joao Silva",
        "documento": "12345678901"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

:::

## Erros de Autenticacao

Quando a autenticacao falha, a API retorna um dos seguintes erros:

### API Key Ausente

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "O cabecalho X-API-Key e obrigatorio",
    "details": "Inclua sua API Key no cabecalho X-API-Key da requisicao"
  }
}
```

### API Key Invalida

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key invalida ou expirada",
    "details": "Verifique se a chave esta correta e ativa no portal"
  }
}
```

### API Key Revogada

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "REVOKED_API_KEY",
    "message": "Esta API Key foi revogada",
    "details": "Gere uma nova chave no portal ou entre em contato com o suporte"
  }
}
```

## Boas Praticas

::: warning Seguranca da API Key
Sua API Key e uma credencial sensivel. Nunca a exponha em codigo do lado do cliente (frontend), repositorios publicos ou logs de aplicacao.
:::

### Recomendacoes de Seguranca

1. **Armazene com seguranca**
   - Use variaveis de ambiente ou servicos de gerenciamento de segredos
   - Nunca commite API Keys em repositorios de codigo

2. **Restrinja permissoes**
   - Use chaves de sandbox para desenvolvimento e testes
   - Mantenha chaves de producao apenas em servidores seguros

3. **Monitore o uso**
   - Acompanhe as requisicoes no painel administrativo
   - Configure alertas para atividades suspeitas

4. **Rotacione periodicamente**
   - Troque suas chaves a cada 90 dias
   - Revogue imediatamente chaves comprometidas

```bash
# Exemplo: usando variavel de ambiente
export MONETARIE_NPC_API_KEY="pk_live_abc123def456"

curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/health" \
  -H "X-API-Key: $MONETARIE_NPC_API_KEY"
```

## Rotacao de Chaves

Para rotacionar sua API Key sem interromper o servico:

### Passo a Passo

1. **Gere uma nova chave** no [Monetarie Portal](https://npcadmin-dev.fluxiq.com.br)
2. **Atualize sua aplicacao** com a nova chave
3. **Teste a nova chave** em ambiente de staging
4. **Implante em producao** com a nova chave
5. **Revogue a chave antiga** apos confirmar que tudo funciona

::: tip Periodo de Transicao
Recomendamos manter ambas as chaves ativas por pelo menos 24 horas durante a transicao para garantir que todos os servicos estejam atualizados.
:::

### Gerenciamento via Portal

No Monetarie Portal voce pode:

- Visualizar todas as suas API Keys
- Gerar novas chaves de sandbox ou producao
- Revogar chaves comprometidas
- Monitorar o uso de cada chave
- Configurar alertas de seguranca

## Proximos Passos

- [Ambientes](/environments) - Entenda os ambientes disponiveis
- [Criar Boleto](/api/boletos) - Registre seu primeiro boleto
- [Codigos de Erro](/reference/errors) - Referencia completa de erros