Sandbox

Test your integration without real scans.

Test your integration without real scans. With sandbox mode enabled, provisioning calls sent with the X-Aegis-Sandbox: true header are simulated, and the scenario endpoints let you choose which mock scan results (clean, warnings or critical) your test customers see.

Sandbox endpoints are not rate limited.

The WHMCS module drives this automatically when its Sandbox Mode setting is on. These endpoints are for custom integrations and manual testing.

Sandbox status

GET/api/v1/sandbox/status

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Whether sandbox mode is on for your account, the active mock scenario, and how many sandbox endpoints exist.

Example request

curl -X GET 'https://portal.example.com/api/v1/sandbox/status' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "success": true,
  "data": {
    "sandbox_enabled": true,
    "sandbox_scenario": "warnings",
    "sandbox_disabled_at": null,
    "onboarding_completed_at": null,
    "sandbox_endpoint_count": 2,
    "can_re_enable": true
  }
}

Errors

Code	Status	Meaning
`404`	404	Your account has no hosting-partner profile.

Set the sandbox scenario

POST/api/v1/sandbox/scenario

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Choose which mock scan results sandbox endpoints report: clean (no issues), warnings (web ports) or critical (database ports exposed).

Body parameters

Name	Type	Required	Notes
`scenario`	string	Required	The mock scenario to activate.one of: clean, warnings, critical

Example request

curl -X POST 'https://portal.example.com/api/v1/sandbox/scenario' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario": "critical"
}'

Response: 200

{
  "success": true,
  "message": "Sandbox scenario updated",
  "scenario": "critical"
}

Errors

Code	Status	Meaning
`403`	403	Sandbox mode is not enabled for your account.
`404`	404	Your account has no hosting-partner profile.

Sandbox activity log

GET/api/v1/sandbox/logs

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Recent simulated provisioning calls with their request and response payloads, useful when debugging a module or integration in sandbox mode.

Query parameters

Name	Type	Required	Notes
`limit`	integer	Optional	How many log entries to return.max:100

Example request

curl -X GET 'https://portal.example.com/api/v1/sandbox/logs?limit=25' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "success": true,
  "data": [
    {
      "id": 118,
      "action": "provision",
      "request_data": {
        "whmcs_product_id": 12,
        "nickname": "Test endpoint"
      },
      "response_data": {
        "success": true,
        "sandbox": true
      },
      "created_at": "2026-07-12T09:20:00+00:00"
    }
  ],
  "count": 1
}

Errors

Code	Status	Meaning
`404`	404	Your account has no hosting-partner profile.

Preview a mock scan result

GET/api/v1/sandbox/scan-result

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

See the mock scan payload the active (or a chosen) scenario produces, without creating anything.

Query parameters

Name	Type	Required	Notes
`scenario`	string	Optional	Preview a specific scenario instead of the active one.one of: clean, warnings, critical

Example request

curl -X GET 'https://portal.example.com/api/v1/sandbox/scan-result?scenario=warnings' \
  -H 'Authorization: Bearer $AEGIS_API_KEY'

Response: 200

{
  "success": true,
  "sandbox": true,
  "data": {
    "status": "warnings",
    "open_ports": [
      { "port": 80, "service": "http", "risk": "low" },
      { "port": 443, "service": "https", "risk": "low" }
    ],
    "risk_score": 20,
    "risk_level": "medium",
    "message": "Standard web server ports detected (sandbox mode)",
    "sandbox": true,
    "scanned_at": "2026-07-12T09:30:00+00:00"
  }
}

Errors

Code	Status	Meaning
`403`	403	Sandbox mode is not enabled for your account.
`404`	404	Your account has no hosting-partner profile.

Create a sandbox endpoint

POST/api/v1/sandbox/provision

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Create a simulated endpoint that reports mock scan data and never triggers real scans. Requires the X-Aegis-Sandbox: true header.

Body parameters

Name	Type	Required	Notes
`whmcs_product_id`	integer	Optional	WHMCS product to associate with the mock endpoint.
`nickname`	string	Optional	Display name for the mock endpoint.max:255

Example request

curl -X POST 'https://portal.example.com/api/v1/sandbox/provision' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "whmcs_product_id": 12,
  "nickname": "Test endpoint"
}'

Response: 201

{
  "success": true,
  "sandbox": true,
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
  "ip_address": "192.0.2.24",
  "nickname": "Test endpoint",
  "message": "Sandbox endpoint created successfully (no real scans)"
}

Errors

Code	Status	Meaning
`400`	400	The `X-Aegis-Sandbox: true` header is missing.
`SANDBOX_DISABLED`	403	Sandbox mode is not enabled for your account (it auto-disables after onboarding completes).
`404`	404	Your account has no hosting-partner profile.

Suspend a sandbox endpoint

POST/api/v1/sandbox/suspend

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Simulate suspending a sandbox endpoint. Requires the X-Aegis-Sandbox: true header.

Body parameters

Name	Type	Required	Notes
`endpoint_id`	uuid	Required	The sandbox endpoint UUID.

Example request

curl -X POST 'https://portal.example.com/api/v1/sandbox/suspend' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
}'

Response: 200

{
  "success": true,
  "sandbox": true,
  "message": "Sandbox endpoint suspended successfully (simulated)"
}

Errors

Code	Status	Meaning
`400`	400	The `X-Aegis-Sandbox: true` header is missing.
`SANDBOX_DISABLED`	403	Sandbox mode is not enabled for your account.

Unsuspend a sandbox endpoint

POST/api/v1/sandbox/unsuspend

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Simulate unsuspending a sandbox endpoint. Requires the X-Aegis-Sandbox: true header.

Body parameters

Name	Type	Required	Notes
`endpoint_id`	uuid	Required	The sandbox endpoint UUID.

Example request

curl -X POST 'https://portal.example.com/api/v1/sandbox/unsuspend' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
}'

Response: 200

{
  "success": true,
  "sandbox": true,
  "message": "Sandbox endpoint unsuspended successfully (simulated)"
}

Errors

Code	Status	Meaning
`400`	400	The `X-Aegis-Sandbox: true` header is missing.
`SANDBOX_DISABLED`	403	Sandbox mode is not enabled for your account.

Terminate a sandbox endpoint

POST/api/v1/sandbox/terminate

Auth: Bearer API keyRate limit: Not rate limited (sandbox)

Simulate terminating a sandbox endpoint (the mock endpoint is deleted). Requires the X-Aegis-Sandbox: true header.

Body parameters

Name	Type	Required	Notes
`endpoint_id`	uuid	Required	The sandbox endpoint UUID.

Example request

curl -X POST 'https://portal.example.com/api/v1/sandbox/terminate' \
  -H 'Authorization: Bearer $AEGIS_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint_id": "9f2c1e4a-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
}'

Response: 200

{
  "success": true,
  "sandbox": true,
  "message": "Sandbox endpoint terminated successfully (simulated)"
}

Errors

Code	Status	Meaning
`400`	400	The `X-Aegis-Sandbox: true` header is missing.
`SANDBOX_DISABLED`	403	Sandbox mode is not enabled for your account.

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