Account-Wide Target Groups API

The Account-Wide Target Groups API returns the IP-based target groups of every security-enabled (WAF) domain in an account, in one request. An optional name filter narrows the response to target groups with a specific name.

It replaces the two-step pattern of calling the Security-Enabled Domains API and then calling the per-domain Target Groups API once for each domain returned.

Use it to find where a target group name exists across your account before adding or removing targets. The add and remove operations themselves remain per-domain and are addressed by target group id. See the Target Groups API .

Prerequisite#

1. You must have at least one domain configured on Nitrogen with security (WAF) enabled.
2. You must have a service account configured with at least Viewer access to the account. If not, you can refer this article for the same.

Endpoint#

List Account Target Groups#

Retrieve the target groups of all security-enabled domains in an account.

Request Details#

GET https://dash.n7.io/api/v2/security/account/{account}/target-groups
Authorization: Token <api-key-of-service-account>

If using Postman, set the Auth Type to No Auth. And then set the Authorization header in the Headers section.

Path Parameters#

• account (required): The unique account identifier (a 6-character uppercase alphanumeric code, e.g., AB12CD).

Query Parameters#

• name (optional): Return only target groups whose name matches this value exactly. The match is case-sensitive and is not a pattern or substring match. When omitted, all target groups are returned.

Example Request#

curl -X GET "https://dash.n7.io/api/v2/security/account/AB12CD/target-groups" \
	-H "Authorization: Token <api-key-of-service-account>"

Filtering by name:

curl -X GET "https://dash.n7.io/api/v2/security/account/AB12CD/target-groups?name=Office%20IP%20Group" \
	-H "Authorization: Token <api-key-of-service-account>"

Response#

On success (HTTP 200), returns the matching target groups. Each entry carries the domain it belongs to and its id, which together address it in the per-domain add and remove endpoints.

{
	"account": "AB12CD",
	"targetGroups": [
		{
			"domain": "shop.example.com",
			"id": "9f1c2b77-5d41-4a0e-8f0a-2c7b1d44aa31",
			"name": "Office IP Group",
			"ipv4": [
				"192.0.2.1"
			],
			"ipv6": [],
			"entries": 1
		},
		{
			"domain": "www.example.com",
			"id": "e28f3a38-c649-4eb1-995a-b68e7dc71e0c",
			"name": "Office IP Group",
			"ipv4": [
				"192.0.2.1",
				"198.51.100.0/24"
			],
			"ipv6": [
				"2001:db8::1"
			],
			"entries": 3
		}
	]
}

If no target group matches, an empty response is returned:

{
	"account": "AB12CD",
	"targetGroups": []
}

Behavior and Constraints#

1. Security-Enabled Only: Only domains with security (WAF) features enabled are included. Domains without WAF are omitted.
2. Exclusions: Disabled domains are never included in the response.
3. In-Use Target Groups Only: A target group appears only once it is referenced by a Content Block. IP-based condition groups that are not yet in use are not returned, which matches the behavior of the per-domain Target Groups API .
4. Permission Scoping: Only domains your service account can view are included. A service account with account-level access but a restricted domain list sees only its permitted domains.
5. Names Are Not Unique: The same target group name can exist on several domains, and a single domain can hold more than one target group with the same name. Always use the domain and id pair from this response to address a target group in the add and remove endpoints, never the name alone.
6. Ordering: Results are grouped by domain, with domains in ascending alphabetical order.

Related#

• Security-Enabled Domains API — list the security-enabled domain names in an account, without their target groups.
• Target Groups API — retrieve a single target group and dynamically add or remove targets for a specific domain.

Error Responses#

When an error occurs, the API returns a non-200 HTTP status code with the following JSON payload:

{
	"code": <error_code>,
	"message": "<error_message>",
	"details": []
}