# 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

```bash
export BUCKER_SERVER_KEY=bkr_sik_...      # read by the Node and Python SDKs
```

```ts
// Node
init({ dsn, serverKey: process.env.BUCKER_SERVER_KEY })
```

```python
# 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.
