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_keyenvelope (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_previewsays 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.