Skip to content
Witen

Witen API

Use https://collector.witenlabs.com for installation API requests.

Authentication boundaries

  • Browser customer APIs use the signed-in website session.
  • Enrolled sites and servers use a host-specific wts- bearer credential in the Authorization: Bearer header.
  • wte- enrollment tokens are single-use and expire after 15 minutes by default.
  • Administrative and service APIs require separate privileged authentication.

Never deploy a fleet ownership credential to individual hosts. Exchange an enrollment token once and retain only the resulting installation credential.

Enrollment exchange

POST /api/v1/enrollments/exchange
Content-Type: application/json

{
  "enrollment_token": "wte-...",
  "sensor_id": "unique-asset-name"
}

Treat the returned wts- value as a secret. An enrollment token cannot be reused after a successful exchange.

Inbound protection and reporting

| Method and path | Purpose | Authentication | | --- | --- | --- | | GET /health | Check Collector availability. | None | | POST /api/v1/events | Report security events from an enrolled site or server. | Installation bearer credential | | GET /api/v1/blocklist/free | Get up to 50 IPs from the standard feed, with a 14-day eligibility delay. | Valid license or installation bearer credential | | GET /api/v1/blocklist/high | Get the higher-score inbound feed used by Warden's default configuration. | Paid license or paid installation bearer credential | | GET /api/v1/blocklist-profiles/wordpress | Get Witen-observed WordPress attack sources. | Valid license or installation bearer credential | | GET /api/v1/blocklist-profiles | List available feed profiles and strictness choices. Does not return IPs. | None | | GET /api/v1/advisories | List publisher-confirmed WordPress advisories and privacy-thresholded exploitation observations. | Customer or service-scoped credential |

The tiered routes also include max, medium, and low; these require a paid license. Their default response is one address per line; send Accept: application/json for JSON. /api/v1/bad-ips and /api/v1/blocklist are authenticated compatibility routes for inbound lists.

The WordPress profile uses WordPress-specific native observations. Its current Free access does not apply the standard feed's top-50 cap or 14-day delay. Installation update frequency is separate from feed eligibility: WordPress refreshes daily on Free and Starter.

Outbound protection

GET /api/v1/bad-ips/outbound returns destinations for egress protection, such as command-and-control infrastructure. It is a separate feed from the inbound blocklists above and requires a valid license or installation credential.

Historical external comparisons

Global administrators can use the private admin route GET /api/v1/admin/feed-history/{ip}?since=...&at=...&limit=200 to inspect sampled external-feed presence, confirmed absence, failed checks, and supplied source metadata. since and at are Unix seconds; the maximum limit is 1000. This route is not exposed on the public API host. It reads stored history without querying providers. External feeds are comparison evidence and never supply Witen's native reputation score or inbound enforcement decisions.

Vulnerability advisory feed

GET /api/v1/advisories?limit=50&offset=0 returns only public lifecycle states. Each record identifies its source and publisher, preserves affected and fixed version evidence, and uses an empty affected_versions value when the source does not establish a range. It never interprets an unknown range as every version.

Exploitation observations appear only when a separately validated classifier signature matches at least three independent sensors. These aggregates contain event, sensor, and source-address counts, but no contributing customer, hostname, request, sensor identity, or source address. A missing observation means Witen has no publishable match; it does not prove that exploitation has not occurred.

Failure handling

Clients should use bounded exponential backoff, preserve event ordering, respect response status codes, and avoid replacing credentials merely because the Collector is temporarily unavailable. Warden continues local detection and enforcement during Collector outages.