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

# IP Binding

> How Enver pins API tokens to specific IP addresses to prevent token theft.

# IP Binding

When an API token is created, Enver records the IP address of the request. Every subsequent request using that token is validated against the stored IP. **A stolen token cannot be used from a different machine.**

## How it works

```
Token creation (POST /tokens from IP 203.0.113.5)
      │
      ▼
  Stored in DB: { tokenHash, ipAddress: "203.0.113.5" }

Later request (GET /envs from IP 198.51.100.9)
      │
      ▼
  Middleware checks:
    apiToken.ipAddress === requestIp?
    "203.0.113.5" === "198.51.100.9" → false
      │
      ▼
  403 Invalid IP address for this token
```

## IP source headers

The middleware reads the IP from these headers in order:

1. `x-forwarded-for` (set by reverse proxies / load balancers)
2. `x-real-ip` (set by Nginx)
3. Falls back to `"unknown"`

## Known edge cases

| Scenario                                     | Behaviour                                                             |
| -------------------------------------------- | --------------------------------------------------------------------- |
| Developer on a dynamic IP (e.g. home ISP)    | Token may stop working after IP changes — revoke and create a new one |
| CI/CD behind a NAT                           | All runners share one egress IP — works fine                          |
| IPv4 vs IPv6 loopback (`127.0.0.1` vs `::1`) | Both treated as localhost                                             |
| Token stored with `"unknown"` IP             | IP validation is skipped for that token                               |

## Best practices

* Create dedicated tokens per machine / CI runner
* Use short TTL (`ttlDays: 7`) for short-lived jobs
* Revoke tokens immediately if a machine is decommissioned or compromised