Allowed Ports

Manage Allowed Ports rules: the ports a customer expects to be open.

Manage Allowed Ports rules: the ports a customer expects to be open. A rule can target a single endpoint or apply globally, and covers a port range and protocol. Creating a rule that matches an open alert resolves that alert automatically. (For historical reasons the resource path is /whitelists.)

Rule counts per endpoint

GET/api/v1/whitelists/endpoint-summary

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

How many Allowed Ports rules each of a customer's endpoints has, plus the count of global rules.

endpoints and global_count are duplicated at the top level for backwards compatibility. Read them from data.

Query parameters

Name	Type	Required	Notes
`whmcs_customer_id`	integer	Required	The customer to summarize.

Example request

curl -X GET 'https://portal.example.com/api/v1/whitelists/endpoint-summary?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "data": {
    "endpoints": [
      {
        "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
        "ip_address": "203.0.113.10",
        "nickname": "Web server",
        "rule_count": 4
      }
    ],
    "global_count": 2
  },
  "endpoints": [
    {
      "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "ip_address": "203.0.113.10",
      "nickname": "Web server",
      "rule_count": 4
    }
  ],
  "global_count": 2
}

List Allowed Ports rules

GET/api/v1/whitelists

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

List Allowed Ports rules, 25 per page. Filter to one customer, one endpoint, a scope, or active/expired status.

This group returns standard Laravel resource envelopes (data / links / meta), not the success envelope used by the provisioning and alerts groups.
Each rule may also carry a nested endpoint object (the full endpoint resource) when its endpoint relation is loaded. Endpoint-scoped rules include it on every read here.

Query parameters

Name	Type	Required	Notes
`whmcs_customer_id`	integer	Optional	Limit results to one customer's rules.
`endpoint_id`	uuid	Optional	Limit results to rules for one endpoint.
`scope`	string	Optional	Filter by rule scope.one of: global, endpoint
`status`	string	Optional	Filter by rule status.one of: active, expired
`per_page`	integer	Optional	Page size (default 25).
`page`	integer	Optional	Page number.

Example request

curl -X GET 'https://portal.example.com/api/v1/whitelists?whmcs_customer_id=1042&endpoint_id=9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b&per_page=25&page=1' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "data": [
    {
      "id": "8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
      "tenant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "port": 443,
      "port_start": 443,
      "port_end": 443,
      "range_label": "443",
      "protocol": "tcp",
      "service": "https",
      "justification": "Standard TLS traffic for the customer's web store",
      "auto_suggested": false,
      "expires_at": null,
      "created_by": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "created_at": "2026-07-01T10:00:00+00:00",
      "updated_at": "2026-07-01T10:00:00+00:00",
      "is_active": true,
      "scope_label": "Endpoint-Specific"
    }
  ],
  "links": {
    "first": "…",
    "last": "…",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Create an Allowed Ports rule

POST/api/v1/whitelists

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Allow a port (or port range) so it stops raising alerts. A rule covers one endpoint (scope: endpoint) or every endpoint (scope: global), and creating it resolves any open alert it matches. Overlapping rules are rejected.

scope defaults from your input: sending endpoint_id implies scope: endpoint, otherwise global.
Omitting port_end creates a single-port rule.

Body parameters

Name	Type	Required	Notes
`port_start`	integer	Required	First port of the range.min:1 · max:65535
`port_end`	integer	Optional	Last port of the range; omit for a single port.min:1 · max:65535 · gte:port_start
`protocol`	string	Required	Protocol the rule covers; `` means both TCP and UDP.one of: tcp, udp,
`service`	string	Optional	Label for what runs on the port.max:100
`justification`	string	Required	Why the port should stay open (10–500 characters), shown in audits.min:10 · max:500
`scope`	string	Required	Whether the rule covers one endpoint or all of them.one of: global, endpoint
`endpoint_id`	string	Optional	The endpoint the rule covers; required when scope is `endpoint`.required if: scope,endpoint · Rule::exists('endpoints', 'id')->where(function ($query) { $tenant = tenancy()->tenant; $query->where('tenant_id', $tenant?->getTenantKey() ?? 'NO_TENANT'); })
`expires_at`	date	Optional	Optional expiry; the rule stops matching after this date.after:today
`whmcs_customer_id`	integer	Optional	Customer creating the rule, for ownership checks.

Example request

curl -X POST 'https://portal.example.com/api/v1/whitelists' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "port_start": 443,
  "port_end": 443,
  "protocol": "tcp",
  "service": "https",
  "justification": "Standard TLS traffic for the customer'\''s web store",
  "scope": "endpoint",
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
  "expires_at": "2026-12-31",
  "whmcs_customer_id": 1042
}'

Response: 201

{
  "data": {
    "id": "8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
    "tenant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "port": 443,
    "port_start": 443,
    "port_end": 443,
    "range_label": "443",
    "protocol": "tcp",
    "service": "https",
    "justification": "Standard TLS traffic for the customer's web store",
    "auto_suggested": false,
    "expires_at": null,
    "created_by": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
    "created_at": "2026-07-12T09:30:00+00:00",
    "updated_at": "2026-07-12T09:30:00+00:00",
    "is_active": true,
    "scope_label": "Endpoint-Specific"
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

Code	Status	Meaning
`403`	403	The endpoint does not belong to the given `whmcs_customer_id`.
`422`	422	Validation failed, including when the port range overlaps an existing rule for the same scope.

Get an Allowed Ports rule

GET/api/v1/whitelists/{whitelist}

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Fetch one rule, including its endpoint when endpoint-scoped.

Query parameters

Name	Type	Required	Notes
`whmcs_customer_id`	integer	Optional	Customer making the request, for ownership checks.

Example request

curl -X GET 'https://portal.example.com/api/v1/whitelists/8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "data": {
    "id": "8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
    "tenant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "port": 443,
    "port_start": 443,
    "port_end": 443,
    "range_label": "443",
    "protocol": "tcp",
    "service": "https",
    "justification": "Standard TLS traffic for the customer's web store",
    "auto_suggested": false,
    "expires_at": null,
    "created_by": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
    "created_at": "2026-07-01T10:00:00+00:00",
    "updated_at": "2026-07-01T10:00:00+00:00",
    "is_active": true,
    "scope_label": "Endpoint-Specific"
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

Code	Status	Meaning
`404`	404	No rule with that ID in your account (or it does not belong to the given customer).

Update an Allowed Ports rule

PUT/api/v1/whitelists/{whitelist}

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Change a rule's range, protocol, service label, justification, scope or expiry. The same overlap validation as creation applies.

Body parameters

Name	Type	Required	Notes
`port_start`	integer	Required	First port of the range.min:1 · max:65535
`port_end`	integer	Optional	Last port of the range; omit for a single port.min:1 · max:65535 · gte:port_start
`protocol`	string	Required	Protocol the rule covers; `` means both TCP and UDP.one of: tcp, udp,
`service`	string	Optional	Label for what runs on the port.max:100
`justification`	string	Required	Why the port should stay open (10–500 characters).min:10 · max:500
`scope`	string	Required	Whether the rule covers one endpoint or all of them.one of: global, endpoint
`endpoint_id`	string	Optional	The endpoint the rule covers; required when scope is `endpoint`.required if: scope,endpoint · Rule::exists('endpoints', 'id')->where(function ($query) { $tenant = tenancy()->tenant; $query->where('tenant_id', $tenant?->getTenantKey() ?? 'NO_TENANT'); })
`expires_at`	date	Optional	Optional expiry; the rule stops matching after this date.after:today
`whmcs_customer_id`	integer	Optional	Customer making the request, for ownership checks.

Example request

curl -X PUT 'https://portal.example.com/api/v1/whitelists/8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "port_start": 443,
  "port_end": 444,
  "protocol": "tcp",
  "service": "https",
  "justification": "TLS plus the staging listener on 444",
  "scope": "endpoint",
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
  "expires_at": "2026-12-31",
  "whmcs_customer_id": 1042
}'

Response: 200

{
  "data": {
    "id": "8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
    "tenant_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "port": 443,
    "port_start": 443,
    "port_end": 444,
    "range_label": "443-444",
    "protocol": "tcp",
    "service": "https",
    "justification": "TLS plus the staging listener on 444",
    "auto_suggested": false,
    "expires_at": null,
    "created_by": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
    "created_at": "2026-07-01T10:00:00+00:00",
    "updated_at": "2026-07-12T09:30:00+00:00",
    "is_active": true,
    "scope_label": "Endpoint-Specific"
  },
  "meta": {
    "timestamp": "2026-07-12T09:30:00+00:00",
    "version": "v1"
  }
}

Errors

Code	Status	Meaning
`404`	404	No rule with that ID in your account (or it does not belong to the given customer).
`422`	422	Validation failed, including range overlap with another rule.

Delete an Allowed Ports rule

DELETE/api/v1/whitelists/{whitelist}

Auth: Bearer API keyRate limit: 100 requests / minute (platform default)

Remove a rule. Ports it covered raise alerts again on the next scan.

The 204 response has an empty body.

Query parameters

Name	Type	Required	Notes
`whmcs_customer_id`	integer	Optional	Customer making the request, for ownership checks.

Example request

curl -X DELETE 'https://portal.example.com/api/v1/whitelists/8a7b6c5d-4e3f-4a2b-9c8d-7e6f5a4b3c2d?whmcs_customer_id=1042' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 204

null

Errors

Code	Status	Meaning
`404`	404	No rule with that ID in your account (or it does not belong to the given customer).

Compiled from the AegisWhite platform (build 6bffe04, module v1.7.3, 2026-07-14).