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

# Manage the IP allowlist via API

> Read and replace your workspace's IP allowlist with two Identity API operations, and handle every error the operations can return.

Two operations on the Identity API manage the [IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview): one reads it, one replaces it. Use them when you manage security settings from your own tooling instead of the Console.

<Note>
  The reference pages for these two operations are not yet in the API reference. Their parent is [Identity APIs](/en/reference/platform/access-manager/am-identity-apis). This page is the contract until the reference pages land.
</Note>

## The two operations

***

| Operation                       | What it does                                                        | Permission         |
| ------------------------------- | ------------------------------------------------------------------- | ------------------ |
| `GET /v1/security/ip-allowlist` | Returns the stored entries and the surfaces where the list applies. | `security` / `get` |
| `PUT /v1/security/ip-allowlist` | Replaces the whole list and, optionally, the surfaces.              | `security` / `put` |

Both operations live on the Identity API base URL and need a bearer token. The platform resolves your workspace from the token. There is no organization identifier in the path or in the body.

## The body

***

The request body of `PUT` and the response body of both operations have the same shape:

<CodeGroup>
  ```json JSON theme={null}
  {
    "entries": ["203.0.113.0/24", "198.51.100.7"],
    "scopes": ["console", "api"]
  }
  ```
</CodeGroup>

| Field     | Required | Meaning                                                                            |
| --------- | -------- | ---------------------------------------------------------------------------------- |
| `entries` | Yes      | The full list of addresses and CIDR ranges. What you send replaces what is stored. |
| `scopes`  | No       | Where the list applies: `console`, `api`, or both.                                 |

Rules that apply to the fields:

* `entries` is a full replacement. To add one address, send the current list plus the new address.
* The response echoes the entries as the platform stored them. A single address comes back with its prefix: `198.51.100.7` becomes `198.51.100.7/32`.
* `entries: []` deactivates the list. The operation returns `200`.
* An empty stored list serializes as `[]`, never as `null`.
* When you omit `scopes`, the stored scopes stay as they are.
* `scopes: []` keeps the entries but stops enforcement everywhere.
* When you omit `entries`, the operation returns `400` with code `IDE-0001` and nothing changes.

## Examples

***

Replace the placeholders with your Identity API base URL and a bearer token that holds the `security` permission.

<CodeGroup>
  ```bash Read the list theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

  curl -sS "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}"
  ```

  ```bash Activate for Console access theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

  curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "entries": ["203.0.113.0/24", "198.51.100.7"],
      "scopes": ["console"]
    }'
  ```

  ```bash Add API access theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

  curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "entries": ["203.0.113.0/24", "198.51.100.7", "192.0.2.10"],
      "scopes": ["console", "api"]
    }'
  ```

  ```bash Deactivate theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

  curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{ "entries": [] }'
  ```
</CodeGroup>

A successful `PUT` returns `200` with the stored list:

<CodeGroup>
  ```json Response theme={null}
  {
    "entries": ["203.0.113.0/24", "198.51.100.7/32"],
    "scopes": ["console"]
  }
  ```
</CodeGroup>

## Recommended order

***

<Steps>
  <Step title="Register the addresses with only the console scope">
    Send the full list with `"scopes": ["console"]`. Include the address you call from.
  </Step>

  <Step title="Make sure you can still sign in">
    Sign in to the Console from a listed address. Then try from an unlisted address and expect a refusal.
  </Step>

  <Step title="List every integration's outgoing address">
    Collect the address each ERP, webhook sender, scheduled job, and application calls from. Add each one to `entries`.
  </Step>

  <Step title="Add the api scope">
    Send the full list again with `"scopes": ["console", "api"]`. Watch your integrations for `403` responses.
  </Step>
</Steps>

## Errors

***

Every error uses the Access Manager envelope with the fields `code`, `title`, and `message`.

| Status | `code`     | `title`                    | `message`                                                                                                                                      |
| ------ | ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `IDE-0001` | Missing Fields in Request  | Your request is missing one or more required fields.                                                                                           |
| 400    | `IDE-0035` | IP Allowlist Too Large     | The IP allowlist is too large: the combined, comma-separated entries must not exceed 200 characters. Please remove some entries and try again. |
| 400    | `IDE-0036` | Invalid IP Allowlist Entry | The IP allowlist entry `{value}` is not a valid IP address or CIDR block. Please correct it and try again.                                     |
| 400    | `IDE-0037` | Invalid IP Allowlist Scope | The IP allowlist enforcement scope `{value}` is not supported. Please use console, api, or both, and try again.                                |
| 401    | `IDE-0008` | Token Missing              | A valid token must be provided in the request header. Please include a token and try again.                                                    |
| 401    | `IDE-0009` | Invalid Token              | The provided token is expired, invalid or malformed. Please provide a valid token and try again.                                               |
| 403    | `AUT-0021` | IP Not Allowed             | Access from your network is not allowed for this workspace. Contact your administrator.                                                        |

<Warning>
  Inspect the `code` field, not only the status. A `403` with code `AUT-0021` can come back from any protected endpoint, including these two, when your own address is outside an active list. In that case the list did not change and you must call from a listed address.
</Warning>

## Related pages

***

<Columns cols={2}>
  <Card title="IP allowlist" icon="shield-halved" href="/en/platform/access-manager/features/ip-allowlist/overview">
    What the feature protects, how it decides, and what it does not cover.
  </Card>

  <Card title="Access Manager error list" icon="triangle-exclamation" href="/en/reference/platform/access-manager/access-manager-error-list">
    Every Auth and Identity error code, with title and message.
  </Card>
</Columns>