# Authentication

The Monetarie NPC API uses **API Key** authentication to protect all endpoints. Each request must include your key in the HTTP header.

## How It Works

All API requests must include the `X-API-Key` header with your access key:

```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"
```

## API Key Format

API Keys follow a standardized format that identifies the environment:

| Prefix       | Environment | Example                          | Use                              |
|--------------|-------------|----------------------------------|----------------------------------|
| `pk_test_`   | Sandbox     | `pk_test_abc123def456ghi789`     | Testing and staging              |
| `pk_live_`   | Production  | `pk_live_xyz789abc123def456`     | Production environment           |

::: info Environment Identification
The prefix of your API Key automatically determines which environment will be used. It is not possible to use a sandbox key in production and vice versa.
:::

## Complete Example

::: 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())
```

:::

## Authentication Errors

When authentication fails, the API returns one of the following errors:

### Missing API Key

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "The X-API-Key header is required",
    "details": "Include your API Key in the X-API-Key header of the request"
  }
}
```

### Invalid API Key

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API Key",
    "details": "Verify that the key is correct and active in the portal"
  }
}
```

### Revoked API Key

**Status:** `401 Unauthorized`

```json
{
  "error": {
    "code": "REVOKED_API_KEY",
    "message": "This API Key has been revoked",
    "details": "Generate a new key in the portal or contact support"
  }
}
```

## Best Practices

::: warning API Key Security
Your API Key is a sensitive credential. Never expose it in client-side code (frontend), public repositories, or application logs.
:::

### Security Recommendations

1. **Store securely**
   - Use environment variables or secrets management services
   - Never commit API Keys to code repositories

2. **Restrict permissions**
   - Use sandbox keys for development and testing
   - Keep production keys only on secure servers

3. **Monitor usage**
   - Track requests in the admin panel
   - Configure alerts for suspicious activity

4. **Rotate periodically**
   - Change your keys every 90 days
   - Immediately revoke compromised keys

```bash
# Example: using environment variable
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"
```

## Key Rotation

To rotate your API Key without interrupting the service:

### Step by Step

1. **Generate a new key** in the [Monetarie Portal](https://npcadmin-dev.fluxiq.com.br)
2. **Update your application** with the new key
3. **Test the new key** in the staging environment
4. **Deploy to production** with the new key
5. **Revoke the old key** after confirming everything works

::: tip Transition Period
We recommend keeping both keys active for at least 24 hours during the transition to ensure all services are updated.
:::

### Portal Management

In the Monetarie Portal you can:

- View all your API Keys
- Generate new sandbox or production keys
- Revoke compromised keys
- Monitor the usage of each key
- Configure security alerts

## Next Steps

- [Environments](/en/environments) - Understand the available environments
- [Create Boleto](/en/api/boletos) - Register your first boleto
- [Error Codes](/en/reference/errors) - Complete error reference