Skip to content

Authority API

The durable authority replaces whole-snapshot publishing with authenticated producer sessions and atomic, per-namespace transactions.


Every /v2 request:

  1. Uses POST with a JSON body.
  2. Carries Authorization: Bearer TOKEN for a configured credential.
  3. Includes the exact authority identity: cluster, group and epoch, 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.


Opens (or reopens) the producer’s session.

POST /v2/open
Authorization: Bearer TOKEN
{
"cluster": "63000000000000000000000000000000",
"group": "67000000000000000000000000000000",
"epoch": "65000000000000000000000000000000",
"expected_generation": 0,
"nonce": "0123456789abcdef0123456789abcdef"
}
FieldMeaning
expected_generationThe producer’s previous session generation (0 the first time)
nonceNonzero, 32 hex digits; binds retries of this open

A successful open fences every older generation of this producer.

{ "cluster": "…", "group": "…", "epoch": "…", "generation": 1 }

Fences the current generation. The producer’s retained results stay in the bounded registry.


POST /v2/transactions
Authorization: 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 }
]
}
FieldMeaning
generationThe open session’s generation
sequenceContiguous per-session sequence number, starting at 1
namespaceThe knobset every key must belong to
expected_namespaceOptional: require this namespace revision
operations[].keyA knob name in namespace
operations[].valueA knob definition, or null to delete
operations[].expected_revisionOptional: the key’s current modification revision, or 0 for “absent”
operations[].absent_namespace_revisionWith 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.

OutcomeMeaningConsumes the sequence
appliedCommitted with a new revisionyes
no_changeIdentical upsert or absent deleteyes
conflictA precondition failed, or a retry changed its contentsyes
capacityA logical limit would be exceededyes
exhaustedRevision space exhaustedyes
result_unavailableThe retained result for this sequence was evicted; it never executes againn/a
unknown_session, session_fenced, out_of_orderWrong or fenced generation, or a sequence gapno
invalid, identity_conflictMalformed request, or wrong authority identityno

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.


{ "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.

{ "cluster": "…", "group": "…", "epoch": "…", "generation": 1, "sequence": 7 }

Looks up the retained outcome of one of the producer’s own transactions, behind a quorum barrier.


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.


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.

EndpointVersion 1 requestResponse
POST /v2/distribution/session/openDistribution request above plus version:1, optional force_snapshotJSON with version, opaque session, window:0, mode (snapshot or resume) and wait_ms
POST /v2/distribution/session/nextversion, session, after, optional exact published cursor and wait_msOne framed update or bodyless 204
POST /v2/distribution/session/closeversion, sessionIdempotent 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.


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.

EndpointRequestResponse
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) together200, 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.


LimitValue
Live knobs500,000
Namespaces4,096
Producers1,024
Operations per transaction128
Canonical request size256 KiB
Definition size16 KiB
Overrides per definition256
Admitted requests per producer16
Outstanding transactions per producer1
Request slots1,024
Aggregate body reservation16 MiB
Producers grouped into one Raft entry64, 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.