Authority API
The durable authority replaces whole-snapshot publishing with authenticated producer sessions and atomic, per-namespace transactions.
Common Request Rules
Section titled “Common Request Rules”Every /v2 request:
- Uses
POSTwith a JSON body. - Carries
Authorization: Bearer TOKENfor a configured credential. - Includes the exact authority identity:
cluster,groupandepoch, each 32 lowercase hex digits.
Producer identity comes from the credential, never from the body. Duplicate JSON fields, at any depth, are rejected before anything is proposed. Request bodies are limited to 256 KiB. Authentication and body-admission failures close the connection.
Credentials with "publish": false can read and receive distributions, but get
403 from /v2/open, /v2/close and /v2/transactions.
POST /v2/open
Section titled “POST /v2/open”Opens (or reopens) the producer’s session.
POST /v2/openAuthorization: Bearer TOKEN
{ "cluster": "63000000000000000000000000000000", "group": "67000000000000000000000000000000", "epoch": "65000000000000000000000000000000", "expected_generation": 0, "nonce": "0123456789abcdef0123456789abcdef"}| Field | Meaning |
|---|---|
expected_generation | The producer’s previous session generation (0 the first time) |
nonce | Nonzero, 32 hex digits; binds retries of this open |
A successful open fences every older generation of this producer.
POST /v2/close
Section titled “POST /v2/close”{ "cluster": "…", "group": "…", "epoch": "…", "generation": 1 }Fences the current generation. The producer’s retained results stay in the bounded registry.
POST /v2/transactions
Section titled “POST /v2/transactions”POST /v2/transactionsAuthorization: Bearer TOKEN
{ "cluster": "63000000000000000000000000000000", "group": "67000000000000000000000000000000", "epoch": "65000000000000000000000000000000", "generation": 1, "sequence": 1, "namespace": "payments", "expected_namespace": 4, "operations": [ { "key": "payments:new_processor", "value": { "default": 0, "rollout_pct": 10, "rollout_value": 1 }, "expected_revision": 3 }, { "key": "payments:max_retries", "value": { "default": 3 }, "expected_revision": 0, "absent_namespace_revision": 4 }, { "key": "payments:legacy_flag", "value": null } ]}| Field | Meaning |
|---|---|
generation | The open session’s generation |
sequence | Contiguous per-session sequence number, starting at 1 |
namespace | The knobset every key must belong to |
expected_namespace | Optional: require this namespace revision |
operations[].key | A knob name in namespace |
operations[].value | A knob definition, or null to delete |
operations[].expected_revision | Optional: the key’s current modification revision, or 0 for “absent” |
operations[].absent_namespace_revision | With expected_revision: 0: the namespace revision the absence was observed at |
A transaction holds up to 128 operations and is atomic within its namespace. Preconditions are evaluated against the state before the transaction. Checking absence against a namespace revision detects delete-and-recreate races without keeping a tombstone for every deleted key.
Outcomes
Section titled “Outcomes”| Outcome | Meaning | Consumes the sequence |
|---|---|---|
applied | Committed with a new revision | yes |
no_change | Identical upsert or absent delete | yes |
conflict | A precondition failed, or a retry changed its contents | yes |
capacity | A logical limit would be exceeded | yes |
exhausted | Revision space exhausted | yes |
result_unavailable | The retained result for this sequence was evicted; it never executes again | n/a |
unknown_session, session_fenced, out_of_order | Wrong or fenced generation, or a sequence gap | no |
invalid, identity_conflict | Malformed request, or wrong authority identity | no |
If the outcome can’t be determined before the deadline, the request fails with
503 and {"error":"outcome_unknown"}: the transaction may or may not have
committed. Retry the
same generation, sequence and body until you get a terminal outcome. A
retryable overload rejection before admission consumes nothing.
Responses carry the authority identity, the outcome and the resulting
revision. The last 256 results of the current generation are retained: a retry
with identical contents returns the original outcome, a retry with different
contents is a conflict, and a sequence whose result was evicted returns
ResultUnavailable and never executes again.
POST /v2/read
Section titled “POST /v2/read”{ "cluster": "…", "group": "…", "epoch": "…", "namespace": "payments", "keys": ["payments:new_processor", "payments:max_retries"] }A strong read of up to 128 unique keys, behind a quorum barrier. The reply
carries the authority identity, the namespace_revision, the selected knobs
and their key_revisions.
Oversized selections return reply_bound.
POST /v2/result
Section titled “POST /v2/result”{ "cluster": "…", "group": "…", "epoch": "…", "generation": 1, "sequence": 7 }Looks up the retained outcome of one of the producer’s own transactions, behind a quorum barrier.
POST /v2/distribution
Section titled “POST /v2/distribution”Used by managed agents, not by publishers.
{ "cluster": "…", "group": "…", "epoch": "…", "scope": "<64 hex digits>", "namespaces": ["payments"], "profile": 1, "coding": "zstd", "base": { "cluster": "…", "group": "…", "epoch": "…", "scope": "…", "revision": 41 }}The response has type application/vnd.detent.distribution and carries
X-Detent-Profile: 1, X-Detent-Coding, X-Detent-Kind (1 snapshot, 2
delta, 3 progress) and X-Detent-Revision. The body is a sequence of bounded
distribution frames. A delta or progress record is only sent when the retained
history exactly covers the requested base; otherwise the authority sends a
snapshot.
Subscription Sessions
Section titled “Subscription Sessions”All three endpoints require a bearer credential. They bind the effective principal, policy epoch, canonical namespace scope and authority identity. Rotated credentials must still authorize every stored namespace; a session ID grants no access by itself.
| Endpoint | Version 1 request | Response |
|---|---|---|
POST /v2/distribution/session/open | Distribution request above plus version:1, optional force_snapshot | JSON with version, opaque session, window:0, mode (snapshot or resume) and wait_ms |
POST /v2/distribution/session/next | version, session, after, optional exact published cursor and wait_ms | One framed update or bodyless 204 |
POST /v2/distribution/session/close | version, session | Idempotent bodyless 204 |
Update responses additionally carry X-Detent-Session-Version: 1, X-Detent-Session and X-Detent-Window. The client validates those bindings before accepting frames. A 204 advances no cursor and asserts no linearizable freshness. Next requires exact publication feedback for the previous offered window; duplicate feedback is idempotent.
A 409 control identifies snapshot_required, identity_changed, session_out_of_sync or session_busy; 410 identifies session_expired. Snapshot resets include reason (history_lost or representation_limit) and require a new Open with force_snapshot:true. Admission pressure returns a bounded 503. Separate request lanes preserve Close capacity when polls are full. The existing distribution endpoint retains automatic snapshot fallback.
session_busy means the session’s previous answer has not retired yet: the session stays open, and the reader asks again after a short wait.
Namespace History for Relays
Section titled “Namespace History for Relays”A relay mirrors namespace history from a voter, or from another relay, through two routes. Both require a bearer credential whose namespace patterns grant every name asked for. A voter answers both from its own sealed history, with no quorum read, and a relay answers them from its mirror.
| Endpoint | Request | Response |
|---|---|---|
POST /v2/history/layouts | {"namespaces": [name, ...]} | 200, application/vnd.detent.layouts: each live name’s layout at the voter’s latest seal, the seal in the answer’s header |
POST /v2/history/file | {"namespace": name, "name": file}, optionally with "offset" and "length" (above 0) together | 200, application/octet-stream: the bytes of a file that the namespace’s layout names, or at most length of them from offset; 404 otherwise, 416 range_not_satisfiable for an offset at or past the file’s end |
A layouts answer is built from the sealed state alone, so every voter at one seal gives the same bytes. A relay never adopts an answer at an older seal than it holds. Both routes answer 503 not_ready while the voter knows no live leader (/v1/health reports ready false), so a reader never follows a voter cut off from the quorum and reads another, and 503 history_unavailable until positions are enabled and the history is sealed; a layouts request makes the leader propose the enabling entry, as a version 2 session does. A whole file larger than the reply bound answers 413 reply_bound; a range answers at most the reply bound, so a reader reads any file in ranges and resumes from the bytes it holds.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Live knobs | 500,000 |
| Namespaces | 4,096 |
| Producers | 1,024 |
| Operations per transaction | 128 |
| Canonical request size | 256 KiB |
| Definition size | 16 KiB |
| Overrides per definition | 256 |
| Admitted requests per producer | 16 |
| Outstanding transactions per producer | 1 |
| Request slots | 1,024 |
| Aggregate body reservation | 16 MiB |
| Producers grouped into one Raft entry | 64, within 5 ms |
Subscription health adds knobs (the applied authority state size), delivery_captures (active export captures), subscription_sessions, subscription_quorum_reads, subscription_exports and subscription_idle_responses. Parked polls do not capture the authority state or submit new quorum reads until an applied revision makes an update available. A 204 response carries no publication cursor or freshness guarantee.