Skip to main content

Set a network policy by API

info

Imply must enable this feature for you. Contact Imply Polaris support for more information.

A network policy lets you control API access to a project in Imply Polaris. The only supported type of network policy is IP allowlist ("policy":"allow"). You can configure a network policy to only accept network traffic from specific IPv4 addresses and Classless Inter-Domain Routing (CIDR) blocks.

Network policy restrictions apply to regional API resources only. Regional APIs operate at the project level and are only accessible within the cloud service provider and region where Polaris hosts your project. To learn more about the difference between regional and global API resources, see Polaris API resources.

This topic walks you through the process of configuring a network policy for a project using the Network policy API. For information on how to set a network policy in the Polaris UI, see IP allowlist.

Prerequisites​

You must have a Polaris API key with the AdministerNetworkPolicies or ManageNetworkPolicies permissions. To obtain an API key and assign permissions, see API key authentication. For more information on permissions, see Permissions reference.

In the examples below, the API key value is stored in the variable named POLARIS_API_KEY.

Add a network policy​

Network policies are disabled by default. To enable the network policy for a project and add IPv4 entries, send a PATCH request to the /v1/projects/PROJECT_ID/network-policy endpoint. Include the following in your request payload:

  • The enabled property set to true.
  • The entries container object with at least one entry. For each entry, the property name is the IPv4 address or CIDR. The property value is the object that describes the network policy. The entries container object supports up to 20 entries.

For example:

{
  "enabled": true,
  "entries": {
    "203.0.113.0/24": {
        "description": "Documentation CIDR example",
        "policy": "allow"
    }
  }
}

See the Network policy API documentation for more information.

Sample request​

The following example request sets the network policy for a project with the ID 45c024f4-1234-5678-8207-4111d2f80669:

curl --location --request PATCH 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669/network-policy' \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/merge-patch+json" \
--data '{
    "enabled": true,
    "entries": {
        "192.0.2.255": {
            "description": "Example IPv4 address",
            "policy": "allow"
        },
        "198.51.100.0/24": {
            "description": "Example CIDR",
            "policy": "allow"
        }
    }
}'

Sample response​

The following example shows a successful response:

View the response
{
  "enabled": true,
  "entries": {
    "192.0.2.255": {
      "description": "Example IPv4 address",
      "policy": "allow"
    },
    "198.51.100.0/24": {
      "description": "Example CIDR",
      "policy": "allow"
    }
  }
}

Update a network policy​

You can edit or remove individual entries in a network policy or disable the entire policy. When you disable the network policy, Polaris retains the policy without enforcing it and accepts API requests from any IP address.

To update a project's network policy, send a PATCH request to the /v1/projects/PROJECT_ID/network-policy endpoint. See the Network policy API documentation for more information.

To disable a network policy, set the enabled property to false. For example:

{
  "enabled": false
}

To remove an individual entry, set the property name to null. For example:

{
  "entries": {
    "203.0.113.0/24": null
  }
}

Sample request​

The following example request updates the network policy for a project with the ID 45c024f4-1234-5678-8207-4111d2f80669:

curl --location --request PATCH 'https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669/network-policy' \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/merge-patch+json" \
--data '{
    "enabled": true,
    "entries": {
        "198.51.100.0/24": null,
        "203.0.113.0/24": {
            "description": "Updated CIDR",
            "policy": "allow"
        }
    }
}'

Sample response​

The following example shows a successful response:

View the response
{
  "enabled": true,
  "entries": {
    "192.0.2.255": {
      "description": "Example IPv4 address",
      "policy": "allow"
    },
    "203.0.113.0/24": {
      "description": "Updated CIDR",
      "policy": "allow"
    }
  }
}

View a network policy​

To retrieve a project's network policy, send a GET request to the /v1/projects/PROJECT_ID/network-policy endpoint. See the Network policy API documentation for more information.

If you haven't configured a network policy for your project, Polaris returns an empty entries object. For example:

{
  "enabled": false,
  "entries": {}
}

Sample request​

The following example request returns the network policy for a project with the ID 45c024f4-1234-5678-8207-4111d2f80669:

curl --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/45c024f4-1234-5678-8207-4111d2f80669/network-policy" \
--header "Authorization: Basic $POLARIS_API_KEY"

Sample response​

The following example shows a successful response:

View the response
{
  "enabled": true,
  "entries": {
    "192.0.2.255": {
      "description": "Example IPv4 address",
      "policy": "allow"
    },
    "198.51.100.0/24": {
      "description": "Example CIDR",
      "policy": "allow"
    },
    "203.0.113.0/24": {
      "description": "Updated CIDR",
      "policy": "allow"
    }
  }
}

Learn more​

See the following topics for more information: