Authentication and workspace selection
The browser sends a current Clerk session bearer token. OAuth access tokens must match the exact configured REST resource audience, issuer, expiry and operation scopes. A product-installation credential is separately issued, narrowed and revocable.
For a human session, X-Temri-Workspace selects a canonical ws_ workspace ID and current membership is checked on every request. A service key is bound to its workspace; a selector cannot broaden it. Never send caller-created principal objects.
GET /v1/workspaces
Authorization: Bearer <current-session-token>Namespace capabilities
Capabilities are read, observe, verify, correct, forget and admin. OAuth scopes use the temri: prefix, such as temri:read and temri:observe. Default scopes are read and observe. Namespace grants remain required even with an operation scope.
Mutation retries
Every mutation requires an Idempotency-Key. Reuse it for an identical retry: the server replays its result. A changed payload under the same key returns 409. Read-only POST /v1/recall does not need a mutation key. Resolve uncertain writes by replay or readback rather than inventing a new key.
Bounded recall and indexing
Recall accepts authorized namespace selectors, as_of, known_at and a context budget. Writes commit the ledger before asynchronous indexing and return a commit sequence. A min_sequence request can report pending indexing. Preserve partial and degraded status; exhausted refill budgets are not proof of absence.
A min_sequence beyond the indexed sequence remains pending while indexing is disabled. Omit that field only when you deliberately accept retrieval without waiting for indexing. Direct memory reads remain available immediately after the ledger commit.
Errors and privacy
Errors are structured JSON with stable codes and retryability. An unauthorized ID looks like an absent ID. Revoked or expired credentials require renewed authorization; do not fall back to stale private data. Private responses use private, no-store caching.
Generated schema is authoritative
Read /openapi.json for exact inputs, outputs, scopes and bounds. It is generated by the shared catalog owner. Examples in this guide describe the connection contract; never put provider secrets into browser code.