Identity endpoints

The cloud-backed identity map: IP → user (+ groups, hostname), used by the collector's who-is lookup so user: / user_groups: rules can match, and by the dashboard to name traffic. Tenant-scoped via get_tenant_id (Bearer token or session cookie). All paths are under /api on the public host.

GET /v1/identity

List current mappings. Query params: include_expired (default false), limit (default 500).

{ "identities": [ { "ip": "10.0.3.42", "user": "dsmith", "groups": ["engineering"],
                    "source": "ad-userid", "hostname": "dsmith-mbp",
                    "observed_at": 1720000000.0, "expires_at": 1720028800.0 } ],
  "count": 1 }

GET /v1/identity/who-is/{ip}?src_port=51234

Resolve one source to {user, groups, hostname, source}. The collector calls this on the hot path (with a short client-side cache). When src_port is provided and the eBPF host sensor has attributed that flow, the response also carries a workload object ({workload, container, pod, labels}). 404 when nothing is known.

POST /v1/identity/upsert

Body: {ip, user, groups?, source?, hostname?, ttl_seconds?} (TTL default 28800 = 8h). Used by the User-ID connector, the CSV importer, and manual entries.

POST /v1/identity/bulk-upsert

Body: {entries: [{ip, user, groups?, hostname?, ttl_seconds?}...], source?} — batch form of the above; each entry's source falls back to the top-level one.

DELETE /v1/identity/{ip}

Remove a mapping. 404 if none exists.

Agent identity tokens

Verified in-process identity for agents (see In-agent identity):

• GET /v1/identity/agent-tokens — list (admin session). Returns fingerprints and metadata, never the token.
• POST /v1/identity/agent-tokens — mint (admin session). Body {agent}; the raw kat_… token appears only in this response.
• DELETE /v1/identity/agent-tokens/{id} — revoke (admin session). Collectors honor revocation within ~60s.
• POST /v1/identity/agent-token/verify — collector-facing. Body {token} → {valid, agent, fp}; 404 for unknown/revoked (collectors negative-cache this).

Flow attribution (eBPF host sensor)

• POST /v1/attribution/bulk-upsert — the host sensor pushes (src_ip, src_port) → workload entries (short TTL, default 900s).
• GET /v1/attribution/resolve?src_ip=…&src_port=… — resolve one flow; 404 when unattributed.

For the resolution model and why names apply retroactively, see Concepts: Identity model.