Local APIs

The Companion Agent exposes a small HTTP surface on the loopback interface only (127.0.0.1). It is never reachable from the network. Callers - the OSDF viewer and allowlisted browser origins - use it to request access decisions and short-lived session assertions.

Loopback only

The broker binds exclusively to 127.0.0.1 (and ::1). It does not listen on 0.0.0.0 and refuses requests whose Origin is not on the configured allowlist.

Base URL

text

http://127.0.0.1:7843

The port is fixed per install and discoverable via the local handshake file written to the OS-appropriate per-user data directory. All responses are JSON.

Origin allowlisting

Every request must carry an Origin header that matches the policy-distributed allowlist (for example, the viewer's origin and your tenant's document portal). Requests with a missing or unlisted origin are rejected with 403 before any work is done.

text

Origin: https://viewer.osdfsystems.com

Endpoints

Method	Path	Purpose
`GET`	`/v1/status`	Current trust posture (trusted / degraded / locked).
`POST`	`/v1/session/assert`	Mint a short-lived, audience-bound session assertion.
`POST`	`/v1/access/evaluate`	Request an access decision for a document + action.
`GET`	`/v1/device/identity`	Return the device's public attestation material.
`GET`	`/v1/decisions/recent`	List recent signed decision events for the UI.

Request a session assertion

Assertions are audience-bound (scoped to a single relying party) and short-lived (seconds to a few minutes). They cannot be replayed against a different audience.

bash

curl -X POST http://127.0.0.1:7843/v1/session/assert \  -H "Origin: https://viewer.osdfsystems.com" \  -H "Content-Type: application/json" \  -d '{ "audience": "viewer.osdfsystems.com", "ttl": "120s" }'

json

{  "assertion": "eyJhbGciOiJFZERTQS// …",  "audience": "viewer.osdfsystems.com",  "expires": "2026-02-11T17:11:00Z",  "device_bound": true}

Evaluate an access request

bash

curl -X POST http://127.0.0.1:7843/v1/access/evaluate \  -H "Origin: https://viewer.osdfsystems.com" \  -H "Content-Type: application/json" \  -d '{ "doc_id": "01J9…", "action": "open", "compartment": "clinical" }'

json

{  "decision": "ALLOW",  "lease_id": "lse_8f2…",  "expires": "2026-02-11T17:16:00Z",  "obligations": ["watermark", "no_export"],  "audit_event": "evt_4c1…"}

Possible decision values are ALLOW, WARN, and DENY. When trust evidence is insufficient - for example, an expired lease while offline - the Agent returns DENY (fail-closed).

Security properties

Loopback-bound - not exposed to the network.
Origin-allowlisted - only trusted callers are served.
Audience-bound assertions - scoped to one relying party, short TTL.
Device-bound - assertions and leases are tied to the hardware key.

See authentication for assertion details and the security model for the full threat treatment.