Skip to content
bucker

The server ingest key: proving telemetry came from your own servers

Every project has a public DSN key. It is public by design: it ships inside browser bundles, so anyone who can read one of your pages can send telemetry that looks like yours. For most projects that is fine. When it is not, because an agent or a person acts on what your telemetry says, you can issue a server ingest key: a secret that only your own servers hold, sent beside the DSN.

Bucker then records, for every envelope, who it can say sent it. That record is the origin.

Origin What it means
server_key The request carried a live server key of this project. Only a process holding your secret sends this.
public_dsn The request carried the public DSN key alone. This is what every Sentry SDK sends, and what a stranger who read your page's source can send too.
relayed Your own server forwarded a browser's envelope through the relay door, with the server key and the signed-in user.
none Written before origin existed, or by a path that decides none. Treated as unsigned, never promoted.

The origin is decided at the door and written on the queue row; the worker stamps it on every event, span and log record the envelope produces. Nothing inside an envelope can claim an origin: a payload that says "origin": "server_key" is stamped what the door decided.

Issuing a key

A key is issued by a person, never by an agent, in the project's settings (or POST /orgs/:org/projects/:project/ingest-origin/server-keys). It needs org:admin (an owner), a stated reason and the person's own session. A delegated OAuth client, an agent, a service and a token with no session are refused whatever scope they hold, and there is no tool for it.

  • The key looks like bkr_sik_ followed by 43 characters. It is shown once, in the create response, which is never cached. Bucker stores only its SHA-256 digest, so nobody can show it again: if you lose it, mint another.
  • A project may hold up to five live keys, so rotation is: mint the new key, deploy it, revoke the old one. A revoke is immediate on the machine that takes it and within five seconds on the others.
  • Creating and revoking write an audit row (the key's id, label and your reason, never the key) and alert the organization's owners.
  • The prefix bkr_sik_ is recognised by secret scanners; a key committed by accident should be revoked at once.

Sending it

export BUCKER_SERVER_KEY=bkr_sik_...      # read by the Node and Python SDKs
// Node
init({ dsn, serverKey: process.env.BUCKER_SERVER_KEY })
# Python
bucker_sdk.init(dsn=..., server_key=os.environ["BUCKER_SERVER_KEY"])

The SDK sends X-Bucker-Server-Key beside the DSN. A Collector sends it through a bearer extension. Never put the key in a browser bundle or a mobile app: the browser SDK has no path for it by design, and a test fails the build if its source names the header.

A key that is present and wrong in any way (malformed, unknown, revoked, another project's, empty) is refused with 401 server_key_required. It is never quietly downgraded to public_dsn: the sender asked to be authenticated and was not, and a revoked key must stop, not silently carry on as an anonymous sender. The SDKs therefore never send a value that is not the right shape: a mistyped key is ignored with one warning, and telemetry keeps flowing as public_dsn.

What a signed origin changes

  • How an agent reads your telemetry. The structure of a server_key envelope (stack frames, file paths, release, environment, transaction) is authenticated structure: a stranger holding the public key could not have shaped it. The text inside it is still untrusted data, scanned and fenced like any other: a server that captured an attacker's request path has put an attacker-chosen string into a frame with a perfectly valid key. Every result's trust block states the origin.
  • How far a verdict can climb. When all the evidence behind a proposed change is public_dsn, decision_preview says so, and the verdict runs one rung lower until a server-key event agrees.
  • What the policy can require. See below.

The origin policy

Two switches per project, both off by default:

Switch Refuses
requireServerKey A server platform's event (node, python, ruby, php, java, go, rust, csharp, elixir and the other closed list) that arrives with the public DSN alone: server_key_required.
relayOnlyBrowser A browser platform's event (javascript, browser) sent straight from a page: origin_policy_refused. Your relay's envelopes are relayed, so they pass.

Mobile, desktop and unknown platforms cannot hold a secret and are refused by neither switch.

Turning a switch on is ingest_origin_policy.narrow: sensitive, always asked, and an agent may file it for a person to approve. The approver is shown last week's share of events the switch would have refused (the seven complete UTC days before today, from this project's own events) and how many would have kept arriving. Turning a switch off is ingest_origin_policy.widen, a person's act with the same rules as issuing a key. Refused envelopes are counted in the drops panel under their reason.

The relay: browser telemetry bound to the signed-in user

A page cannot keep a secret, so point the browser SDK's tunnel at your own backend. Your backend forwards each envelope, unchanged and uncompressed, to

POST https://<ingest host>/api/<projectId>/relay
X-Sentry-Auth: Sentry sentry_key=<public key>
X-Bucker-Server-Key: bkr_sik_...
X-Bucker-Relay-Subject: <the signed-in user's id>     (omit for a signed-out visitor)

The relay accepts only with a live server key of the project the DSN names. It writes the project's keyed pseudonym of the subject on the envelope (over anything the sender put there), so the raw identifier is never stored or logged, and a different project computes a different stamp for the same user. The stored origin is relayed.

Each (project, subject) has its own allowance of 120 envelopes a minute, and signed-out traffic shares a larger one of 600, so a forgery needs a signed-in account, is attributed to it and is capped by it. An over-limit answer is 429 with Retry-After.

A relayed envelope's structure is not authenticated: a browser wrote it and the key only proves who forwarded it.