External Attack Surface API

Maintained by: Aether365 Team Audience: Developers Scope: External Attack Surface (EAS) endpoints - results, scan targets, domain verification, and on-demand scans

The External Attack Surface API reads the outside-in posture of your Microsoft 365 domains (TLS, DNS security, and exposed endpoints), manages which hosts are scanned, and triggers on-demand scans. All endpoints are tenant-scoped from the bearer token. The on-demand scan requires a paid plan.

Get Attack Surface Results

Returns the latest attack surface scan grouped into ssl, dns, and endpoints sections, plus open-issue counts by severity and the current scan targets.

GET /tenants/me/attack-surface

Example Request

curl https://api.aether365.io/tenants/me/attack-surface \
  -H "Authorization: Bearer <token>"

Example Response

{
  "success": true,
  "data": {
    "latestScan": {
      "id": "scan_abc123",
      "status": "completed",
      "completedAt": "2026-06-29T08:00:00Z",
      "passCount": 18,
      "failCount": 6
    },
    "severityCounts": { "Critical": 1, "High": 2, "Medium": 3, "Low": 0 },
    "sections": {
      "ssl": [
        {
          "testId": "EAS.TLS.001",
          "title": "Certificate is valid and not expiring soon",
          "result": "Passed",
          "severity": "High",
          "target": "contoso.com",
          "helpUrl": "https://docs.aether365.io/checks/...",
          "remediation": "..."
        }
      ],
      "dns": [],
      "endpoints": []
    },
    "targets": [
      {
        "id": "tgt_abc123",
        "host": "contoso.com",
        "source": "user",
        "excluded": false,
        "verificationStatus": "verified",
        "verifiedAt": "2026-06-28T12:00:00Z",
        "createdAt": "2026-06-28T11:00:00Z"
      }
    ]
  }
}

Each finding's target is the host it applies to; findings with no host are tenant-wide checks. Group by target to get a per-domain view. Findings also carry a raw object with the underlying check output, and latestScan includes a createdAt timestamp.

---

List Scan Targets

Returns every scan target for the tenant: auto-discovered Microsoft 365 domains and custom domains you added.

GET /tenants/me/attack-surface/targets

A pending custom target also returns a verificationRecord (the DNS TXT value to publish).

---

Add a Custom Target

Adds a custom domain. It starts pending and is not scanned until verified.

POST /tenants/me/attack-surface/targets

Request Body

{ "host": "contoso.com" }

Field	Type	Required	Notes
host	string	Yes	A bare domain name (no scheme, port, or path)

Example Response

{
  "success": true,
  "data": {
    "id": "tgt_new123",
    "host": "contoso.com",
    "source": "user",
    "excluded": false,
    "verificationStatus": "pending",
    "verificationRecord": "aether365-site-verification=ab12cd34..."
  }
}

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	host is not a bare domain name
VALIDATION_ERROR	409	The target already exists

---

Verify a Custom Target

Confirms domain ownership by looking up the published TXT record. On success the target becomes verified and is included in the next scan.

POST /tenants/me/attack-surface/targets/{targetId}/verify

Publish a DNS TXT record on the domain apex with the value returned as verificationRecord (for example aether365-site-verification=ab12cd34...), then call this endpoint.

Errors

Code	HTTP	Description
EAS_TXT_NOT_FOUND	400	The expected TXT record was not found in DNS yet

---

Exclude or Include a Target

Toggles whether a target is scanned. Auto-discovered targets cannot be deleted, only excluded.

PATCH /tenants/me/attack-surface/targets/{targetId}

Request Body

{ "excluded": true }

---

Delete a Custom Target

Removes a custom (user-added) target. Auto-discovered targets return 400 and can only be excluded.

DELETE /tenants/me/attack-surface/targets/{targetId}

---

Trigger an Attack Surface Scan

Starts an on-demand attack surface scan. Requires a paid plan.

POST /tenants/me/attack-surface/scan

Request Body

{ "connectionId": "conn_abc123" }

Field	Type	Required	Notes
connectionId	string	No	Connected Microsoft tenant to scan; omit for the primary

Errors

Code	HTTP	Description
AUTH_INSUFFICIENT_SCOPE	403	Plan does not include External Attack Surface
TENANT_NOT_CONNECTED	400	No connected Microsoft tenant
SCAN_ALREADY_RUNNING	409	An attack surface scan is already in progress
SERVICE_UNAVAILABLE	503	The attack surface scanner is not yet available