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

# IP Controls

> Restrict license usage by IP address to control where your software can run.

IP controls let you restrict which IP addresses can validate a given license. When enabled, KeyPort tracks and enforces IP registration rules at validation time.

## How IP controls work

When a license is validated, KeyPort evaluates IPs in the following order:

<Steps>
  <Step title="Platform blacklist check">
    KeyPort checks the IP against the platform-wide blacklist. Blacklisted IPs are blocked immediately.
  </Step>

  <Step title="Organization blacklist check">
    On Pro and Enterprise plans, KeyPort checks the IP against your organization's blacklist.
  </Step>

  <Step title="Customer blacklist check">
    If the customer attached to the license has an IP blacklist entry, KeyPort blocks that IP before license-level IP registration rules are evaluated.
  </Step>

  <Step title="Per-license blacklist check">
    KeyPort checks the IP against any blacklist configured directly on the license.
  </Step>

  <Step title="IP registration and limits">
    KeyPort checks whether the IP is registered for the license and whether the registration limit has been reached.
  </Step>
</Steps>

## Enabling IP controls

IP controls are configured at the product level. To enable them, turn on the IP system for your product in the KeyPort dashboard. Individual licenses inherit the product's IP settings, including the `max_ips` limit.

## IP registration behavior

How IPs are registered depends on two settings: `track_ip_on_validate` and `auto_register_ip_on_validate`.

* If `track_ip_on_validate` is off, validation does not record the caller's IP at all.
* If `auto_register_ip_on_validate` is off, any IP that isn't already registered returns `ip_not_registered`.
* If auto-registration is on, the first IP to validate can self-register.
* Once at least one active IP is registered, a different unknown IP returns `ip_not_registered`.
* If the license has already reached its `max_ips` limit, any new registration attempt returns `ip_limit_reached`.

<Warning>
  Do not assume that every new IP will auto-register up to `max_ips`. Test your product's exact IP policy to confirm the behavior you expect.
</Warning>

## Validate response fields

When IP controls are active, the validate response includes these fields:

<ResponseField name="ip_registered" type="boolean">
  Whether the calling IP is registered for this license.
</ResponseField>

<ResponseField name="ip_count" type="integer">
  The number of IPs currently registered for this license.
</ResponseField>

<ResponseField name="max_ips" type="integer">
  The maximum number of IPs allowed for this license.
</ResponseField>

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ip_registered": true,
  "ip_count": 1,
  "max_ips": 1
}
```

## Blocking states

If IP validation fails, the response will include one of these states:

| State               | Meaning                                                                             |
| ------------------- | ----------------------------------------------------------------------------------- |
| `ip_blocked`        | The IP is on a blacklist at the platform, organization, customer, or license level. |
| `ip_limit_reached`  | The license is already at its `max_ips` limit; the new IP cannot register.          |
| `ip_not_registered` | The IP is not registered and auto-registration is disabled or blocked.              |

Handle these states in your application to give users appropriate feedback when their IP is not permitted.