DSN and the region model
Format
https://<publicKey>@<region>.<ingestHost>/<projectId>
Example: https://a1b2c3d4@us.ingest.example.com/clx0project0id
| Part | Rules |
|---|---|
| scheme | https (http is tolerated for local development only) |
publicKey |
[A-Za-z0-9_-]+, unique across the install |
| password half | must be empty — a DSN carrying a secret is rejected as malformed |
region |
first hostname label; [a-z][a-z0-9-]{0,15} |
ingestHost |
everything after the region label, port included |
| path | exactly one segment, the project id |
| query / fragment | must be absent |
Parsing lives in domain/src/lib/dsn.ts (parseDsn / buildDsn) and, for SDKs, in
shared/src/protocol/dsn.ts. create-bucker re-implements the same rules locally
so that npx pulls down zero dependencies.
The Sentry-SDK form: the project's number
Every Sentry SDK refuses a DSN whose project segment is not an integer. The JavaScript SDKs
disable themselves without saying so outside debug mode (Invalid Sentry Dsn: Invalid projectId), and sentry-python raises at init (invalid literal for int()). A Bucker
project id is not an integer, so the DSN above cannot be given to an unmodified Sentry SDK.
Each project therefore also has a number (Project.sentryProjectId), and every key reports a
second, equivalent DSN with it, sentryDsn:
https://<publicKey>@<region>.<ingestHost>/<projectNumber>
Use sentryDsn in Sentry.init({ dsn }). Every DSN-authenticated route (the envelope,
OTLP, check-ins, feedback and the rest) accepts either form in its <projectId> path segment.
The number only identifies the project. It never authenticates: the public key must still
belong to the project the path names, so a key addressed at another project's number is
refused with a 403, exactly as with another project's id. Bucker's own SDKs accept both
forms.
The public key is not a credential for anything but ingest
ProjectKey.publicKey appears in client bundles by design. It authenticates ingest
only — it cannot read an issue, list a project, or call the control plane. There is
no secret half to protect, which is why listing keys back to project members is safe
and why the onboarding endpoint can return the DSN.
Legacy Sentry DSNs carried a secret in the password slot. Bucker DSNs never do, and
parseDsn rejects one that tries.
Why the region prefix exists on day one
The first hostname label is the data region. Adding an EU region later is then purely additive — a new hostname, the same identifier scheme — instead of a migration that rewrites every customer's DSN and every config file that quotes it.
The DSN is derived, never stored: key.service.ts builds it from
{ publicKey, projectId, region } on every read. Changing INGEST_HOST or
INGEST_REGION propagates to every key immediately.
Today only us and eu are accepted values for the server's own INGEST_REGION, and
only one region actually runs. The parser accepts any well-formed region label, so
SDKs and the CLI are already forward-compatible.
Ingest endpoint
POST https://<region>.<ingestHost>/api/<projectId>/envelope/
Content-Type: application/x-sentry-envelope (or any type: the route reads the body raw)
The bare form without the trailing slash is registered too, so curl and hand-rolled
clients do not hit a surprise 404.
Authentication is the public key, sent either as the sentry_key query parameter or
inside the envelope header's dsn field. The browser SDK avoids a preflight on every
event, and that takes two things together. First, auth goes in the query string, because
an X-Sentry-Auth header is not CORS-safelisted. Second, the SDK sends
Content-Type: text/plain;charset=UTF-8, which the ingest route accepts because it
ignores the type. Query-string auth with application/x-sentry-envelope is still
preflighted. A sendBeacon built that way is credentialed, so it cannot pass the ingest
route's */no-credentials preflight and is silently dropped.
code/sdks/browser/src/transport.ts (SIMPLE_CONTENT_TYPE) explains why. Do not relax
the server policy to fix this.
A 200 carries { "id": "<eventId>" } and an X-Bucker-Ingest-Disposition header.
It means the envelope was accepted and queued, not that an issue exists yet —
that happens when a worker drains the queue.
A process serves one region, and refuses the rest
INGEST_REGION is also the region this process SERVES. An organization lives in one region
(Organization.region), and a process in another refuses it with 409 and
error.details.redirectTo, the region's API URL. The check is on every path that reaches an
organization, not only the compliance routes:
| Path | Where | What it costs |
|---|---|---|
REST routes naming :orgSlug, and every authenticated route (a :projectId in the URL, an org-bound credential) |
plugins/residency.ts, after authentication |
one cached lookup per org per 30 s |
| Ingest, OTLP, the platform drains and the replay recorder config | lib/ingest-door.ts (and replay/config-routes.ts), right after the DSN key resolves |
one cached lookup per project per 30 s |
| Explore | explore/printer/guard.ts, on the org row it already loads |
nothing |
| MCP tools | mcp-server/src/tools/common.ts and the status resolvers |
nothing for an issue, one cached lookup otherwise |
| Worker job claims | db/src/queue/postgres-driver.ts and the remediation claim |
one semi-join in the claim statement |
Details a client can rely on:
GET /orgs/:orgSlug/compliance/residencyis exempt. It reportsservedByThisRegion: false, which is the answer that explains the refusals everywhere else.- On an authenticated route, a signed-in caller who is not a member of the org gets a 404
and never the 409: whether someone else's organization lives in
euis not theirs to learn, and 404 is what the other region's own deployment would answer here. The route itself never runs, even one that authorizes non-members (the operator console). On a public or optional-auth route (status pages, SSO entry points) everyone gets the 409, as an anonymous caller does. redirectServing: falsein the 409 means the named region is not operating.euis listed in the registry and not active: it has no DNS name and no stores, so there is nowhere to redirect to yet.- The ingest door takes the project from the key, never from the body.
- The region of an org is cached for 30 seconds per process. A region migration is the only thing that changes it, and for up to 30 seconds after a cutover a process may still serve the org from its old region (the cutover does not yet evict the cache).
- No token changes. The refusal is made by the resolver, so a token issued before this check
verifies exactly as it did; the audience stays
bucker-mcp.
residency_get (MCP, project:read) tells an agent which region serves the org, which provider
and region hold each store (a ? is "not yet confirmed", never a guess), and any region move in
flight; include: [manifest] adds the published trust manifest from https://bucker.io/trust.json.
Configuration
| Variable | Default | Meaning |
|---|---|---|
INGEST_REGION |
us |
Region label this install stamps into DSNs |
INGEST_HOST |
localhost:4000 |
Ingest host without the region prefix |
INGEST_INLINE_MAX_BYTES |
65536 |
Above this, the raw envelope goes to blob storage instead of the row |
INGEST_MAX_ENVELOPE_BYTES |
20971520 |
Hard reject above this, with an accounted too_large outcome |