API Conventions
UEC exposes a versioned REST API plus SignalR hubs for real-time agent and console communication.
UEC exposes a versioned REST API plus SignalR hubs for real-time agent and console communication.
Base path and versioning
Section titled “Base path and versioning”- A deployment may live behind a base path such as
/xdr/uec. - Tenant URLs add the tenant slug, for example
/xdr/uec/default. - REST endpoints are versioned under
/api/v{version}/.... - The console and agents both use the deployed base path.
Authentication
Section titled “Authentication”| Principal | Mechanism |
|---|---|
| Console user | JWT bearer session/refresh flow |
| SSO user | Entra ID/OIDC callback into the tenant session |
| Agent | Device JWT issued at enrollment |
| WebSocket/SignalR | Short-lived JWT passed on the connection |
| Enrollment | Signed enrollment token for initial registration |
| Automation | Scoped, expiring API token |
Agents and users share JWT bearer semantics, but role/device claims distinguish the principal.
Rate limits
Section titled “Rate limits”| Scope | Default limit |
|---|---|
| User/admin global | 200 requests/minute |
| Agent | 5,000 requests/minute |
| Authentication | 10 requests/minute per IP |
| Registration | 120 requests/minute per IP |
| Forensic batch | Dedicated lower policy |
Limits are operational defaults; deployment configuration and product release can change them.
Errors
Section titled “Errors”Errors use RFC 9457 ProblemDetails with a stable code shaped DOMAIN_NNNN. Common status codes:
| Status | Meaning |
|---|---|
400 |
Invalid request/input |
401 |
Missing or invalid credentials |
403 |
Authenticated but not permitted / module or password-change restriction |
404 |
Resource absent or outside the caller’s scope |
409 |
Concurrent/stale write or duplicate live action |
422 |
Semantic validation failure |
429 |
Rate limit exceeded |
5xx |
Server/upstream failure |
Preserve the correlation id when escalating an error.
Pagination and lists
Section titled “Pagination and lists”List endpoints use cursor-based pagination with page-size defaults and maximums. Filters, facets, sort and search generally run server-side. Very large exports can be capped and must state the cap.
SignalR hubs
Section titled “SignalR hubs”| Hub | Audience | Purpose |
|---|---|---|
/hubs/agent |
Agents | Commands, heartbeat, policy hints, event/inventory/result shipping |
/hubs/events |
Console | Device status, alerts, response/action and other tenant updates |
Agent-side result methods can include an integrity/HMAC handshake. Large forensic/live-response outputs are streamed in bounded frames.
Request size and payloads
Section titled “Request size and payloads”The API permits very large agent package uploads (up to 200 MB by default). Hub messages have a separate lower maximum; event batches use MessagePack plus Zstd compression and acknowledged delivery.
Automation safety
Section titled “Automation safety”- Prefer scoped API tokens over user passwords.
- Record token owner, purpose and expiry.
- Never log bearer tokens or agent credentials.
- Use dry-run/test endpoints where available.
- Treat AMTD integrations as pass-through to the configured upstream tenant.
- Do not invent client-side policy artifacts; use policy APIs.