What is a DSN, and why do error trackers use one?

The definition

A DSN, in the context of error tracking, is the URL the SDK uses to ship events to the backend that receives and stores them.

The abbreviation stands for Data Source Name, a term borrowed from database driver conventions where it describes a connection string that encodes the host, port, database name, and credentials in a single value. Error-tracking tools adopted the same pattern: one string, complete configuration, paste it once.

Sentry popularized the format in the early 2010s when it released its open-source error-tracking server. Every tool that followed, including GlitchTip, Bugsink, and urgentry, adopted the same DSN shape so that existing SDK instrumentation would work without modification. The DSN is now the de facto wire contract for error-tracking ingest across the entire ecosystem.

The SDK reads the DSN at initialization time. After that, every event the SDK captures goes to the host encoded in the DSN, authenticated with the key encoded in the DSN, filed under the project ID encoded in the DSN. The application code that raises exceptions touches none of this directly.

The anatomy of a DSN

A DSN has the structure of a URL with the public key in the username position, the ingest host as the host, and the project ID as the path.

https://PUBLIC_KEY@HOST/PROJECT_ID

Each segment controls a distinct part of the ingest pipeline:

• Scheme (https://). Always HTTPS for any production DSN. Some local development setups use http:// for a DSN pointing at localhost; do not use HTTP in production.
• Public key. The credential that authenticates the ingest request. It sits in the URL username position, before the @. The key has send-only authority: it can deliver events but cannot retrieve them, modify project settings, or access other projects.
• Host. The domain and optional port of the ingest server. For Sentry SaaS this is o<org_id>.ingest.sentry.io. For urgentry it is the domain or IP where you deployed the binary, for example errors.yourdomain.com.
• Project ID. The numeric or alphanumeric identifier of the project on the backend. The backend uses this to route the event to the correct issue store, alert rules, and team assignment policies.

An annotated example pointing at urgentry:

https://a1b2c3d4e5f6@errors.yourdomain.com/4

 ^scheme  ^public_key  ^host                ^project_id

The SDK constructs the ingest endpoint from these components at runtime. For the Sentry envelope format, the endpoint becomes:

https://errors.yourdomain.com/api/4/envelope/

The public key travels as the X-Sentry-Auth header on each request, not as a query parameter. The DSN is parsed once at initialization; you do not see it in individual network requests.

Why error trackers use a DSN instead of a separate API key and endpoint

A DSN bundles the three values an SDK needs into one string so that complete SDK configuration is a single copy-paste operation.

Without the DSN format, configuring an SDK would require three separate settings: an endpoint URL, a project identifier, and an authentication credential. Each setting is a potential misconfiguration: wrong endpoint means events go nowhere, wrong project ID means events land in the wrong bucket, wrong key means every request is rejected. Teams would need to keep three values in sync across every environment and service.

The DSN collapses all three into one value. The project settings UI generates a valid, complete DSN. You copy it, set one environment variable, and the SDK is fully configured. There is no separate auth header to set, no endpoint to look up in documentation, no project ID to cross-reference from a different settings page.

This also makes rotation atomic. When a DSN needs to change, you replace one string everywhere it appears. No partial updates where the key has changed but the endpoint has not.

Public vs secret keys

The modern Sentry SDK uses only the public key for ingest; the secret key is a legacy concept from Sentry’s early API design that has no role in current SDK initialization.

In Sentry’s original architecture, the DSN carried both a public key and a secret key, separated by a colon:

https://PUBLIC_KEY:SECRET_KEY@HOST/PROJECT_ID

The public key authenticated client-side ingest (browser SDKs, mobile apps). The secret key authenticated server-side ingest from environments where the key could be kept private. That distinction made sense when the secret key granted additional capabilities.

Starting with Sentry SDK version 7 (2022), the secret key was deprecated from the DSN. The modern DSN format has no colon-separated secret:

https://PUBLIC_KEY@HOST/PROJECT_ID

What each key can do today:

• Public key. Authorizes event delivery to the ingest endpoint. This is the only credential the SDK needs. It cannot read stored events, modify project configuration, or access any data retrieval API.
• Secret key (legacy). In older Sentry deployments still running pre-v7 DSN format, the secret key was required for the /api/<id>/store/ endpoint on server-side SDKs. Modern ingest paths do not require it. If you see a DSN with a colon-separated value, you are looking at a legacy DSN; current urgentry and current Sentry both accept the shorter public-key-only form.

Requests sent without any valid DSN key return 401 Unauthorized. Requests with a valid public key but to a project ID that does not exist return 404 Not Found. Both are observable in the SDK’s debug log.

The DSN as the only swap point between Sentry, GlitchTip, Bugsink, and urgentry

Every Sentry-compatible error tracker accepts the same DSN format, which means the SDK code is identical across all of them and only the DSN string changes when you switch backends.

The SDK does not know or care what server receives its events. It parses the DSN, constructs the ingest URL, serializes the event into the Sentry envelope format, and sends an HTTP POST. The backend at the other end can be Sentry SaaS, Sentry self-hosted, GlitchTip, Bugsink, or urgentry. The SDK treats them identically.

This is what "compatibility-first" means in practice. urgentry implements 218 of the 218 documented Sentry REST API operations. The compatibility matrix at /sentry-alternative/ lists every operation. But for ingest, the only surface that matters is the DSN shape. If the backend accepts the DSN-derived envelope endpoint, the SDK works with it.

A concrete comparison of the initialization code across two backends:

// Pointing at Sentry SaaS
Sentry.init({
  dsn: "https://a1b2c3d4@o123456.ingest.sentry.io/789",
});

// Pointing at urgentry — only the DSN changes
Sentry.init({
  dsn: "https://a1b2c3d4@errors.yourdomain.com/1",
});

The integration list, the sampling rate, the release string, the environment tag: all of these stay the same. The DSN is the only diff between a Sentry-instrumented service and an urgentry-instrumented one.

In practice, teams keep the DSN in an environment variable (SENTRY_DSN) and change the value at deploy time. No code change, no redeploy of instrumented services, no coordination with the team that owns the SDK configuration. One variable, one value swap.

DSN hygiene

Treat the DSN as a secret in your version control and CI/CD pipeline, even though the public key it contains has ingest-only authority.

The public key cannot exfiltrate your error data. But anyone who obtains your DSN can send events to your project. In practice, this means they can flood your project with synthetic events, exhaust your event quota, trigger your alert rules with fabricated errors, and generally degrade the signal quality of your error tracker. That is enough harm to justify treating the DSN with the same care as any other credential.

Concrete hygiene practices:

• Keep the DSN in environment variables. SENTRY_DSN is the conventional name. All major Sentry SDKs read this variable automatically; you do not need to pass it to Sentry.init() explicitly. Store the value in your secrets manager (Vault, AWS Secrets Manager, GitHub Actions secrets), not in the repository.
• One DSN per project. urgentry and Sentry both support multiple projects under one organization. Give each service its own project and its own DSN. If one DSN leaks, rotating it affects only the one service, not every service in the organization.
• Rotate when leaked. If a DSN appears in a public commit, a Slack log, or a shared screenshot: create a new DSN in project settings, update every service that uses the old one, and revoke the old DSN. Urgentry, like Sentry, allows multiple active DSNs per project to make zero-downtime rotation possible.
• Audit with a secrets scanner. Tools like git-secrets, gitleaks, and GitHub’s secret scanning all support custom patterns. Add a pattern for the DSN format (https://[a-f0-9]+@) to catch accidental commits before they reach a public branch.

The two DSN gotchas worth knowing

Two DSN format variations cause confusion when teams move between Sentry SaaS and self-hosted backends.

Region-suffixed DSNs on Sentry SaaS

Sentry SaaS uses region-specific ingest hosts. A US region DSN looks like:

https://KEY@o123456.ingest.sentry.io/PROJECT_ID

A EU region DSN looks like:

https://KEY@o123456.ingest.us.sentry.io/PROJECT_ID

The region is part of the host, not the path. If you copy a DSN from a Sentry SaaS project and later copy one from a different region, the hosts differ. This matters if your self-hosted urgentry deployment handles events from both regions: your urgentry DSNs have a single host, and the mapping is one-to-one between DSN and deployment.

Self-hosted alternatives including urgentry do not have region suffixes because you choose the host at deploy time. Your DSN host is whatever domain or IP you configured.

Organization-prefixed DSNs in Sentry’s newer auth model

Sentry introduced a new auth token format in 2023 that uses organization-scoped tokens for API access. This is separate from the DSN. The DSN public key is still used for ingest. Organization tokens are used for API operations: creating releases, uploading source maps, querying issues through the REST API.

The confusion arises when documentation conflates the two. If you see a token that starts with sntrys_, that is an organization auth token, not a DSN component. It goes into your CI/CD pipeline for release creation and source-map upload, not into SENTRY_DSN. The DSN and the organization token are separate credentials with separate scopes.

urgentry uses the same separation: a DSN for SDK ingest, separate auth tokens for API operations. The urgentry quickstart walks through both.

Frequently asked questions