Documentation / Administration

Connections & Isolation

How Nexus connections (bridges) govern access to your data sources, how service and user credentials stay strictly isolated so one user's credentials can never resolve for another, and how connection governance protects your databases.

In Nexus, a bridge is a governed, named connection to a data source — a SQL Server, a Postgres database, NetSuite, Monday, or any other supported system. Bridges are how administrators and users wire Nexus to live data without ever pasting raw credentials into reports or pipelines. This page is for administrators and technical users who manage connections and need to understand exactly who can use which credentials, and why one user's credentials can never resolve for another.

What a bridge is

A bridge is identified by its system and a bridge name — for example mssql / production. One adapter type can back many bridges, so two separate SQL Servers are simply two bridges with different names. Reports and pipelines reference a bridge by name; the actual credentials are resolved at run time from Key Vault and never appear in the report or pipeline definition, its version history, or any export.

# A pipeline references a bridge by name only:
async def run(ctx):
    rows = await ctx.adapters.mssql.read(
        ReadQuery(bridge_id="production", ...)
    )
    # Nexus resolves the "production" credentials from your Key Vault at run time.

Two scopes: service vs. user

Every bridge has a scope that determines who owns it and who may use it. This is the central governance decision for any connection.

Scope	Owned by	Who can use it	Managed by
Service	The tenant	Anyone whose permissions let them run the report or pipeline	Administrators
User	One individual	Only that individual	The user themselves

Service bridges are shared, admin-managed connections — the natural choice for a central data warehouse that a whole team queries under one set of governed credentials. A single reviewed login backs many people's work, and the humans never see it.
User bridges let an individual supply their own keys — a personal API token or database login — without an administrator ever seeing the values and without any other user ever being able to use them. This suits systems that enforce per-person entitlements downstream (a user should only see the rows their own login is allowed to see).

How a connection is chosen at run time

Each report and each pipeline carries a bridge mode that decides which scope is consulted when it runs.

Bridge mode	Behavior
Service only (default)	Uses the service bridge only. Never touches any user's credentials.
My credentials only	Uses the running user's own bridge only. If the user has no such bridge, the run fails closed with a clear message.
Mine, then service	Tries the running user's bridge first; falls back to the service bridge if the user has none.

The default is Service only, so existing reports and pipelines behave predictably and never silently reach for a personal credential. In a pipeline, an author sets the mode with a frontmatter directive at the top of the module:

# nexus:bridge_mode user_only

async def run(ctx):
    rows = await ctx.adapters.mssql.read(
        ReadQuery(bridge_id="production", ...)
    )

The identity whose user bridge is eligible is resolved on the server from the authenticated session — never from request input. For an interactive run it is the person who clicked Run. For a scheduled run it is the owner captured when the schedule was created, if any. A background or webhook trigger has no human identity, so "My credentials only" fails closed and "Mine, then service" uses the service bridge. A missing identity can only ever narrow access — never widen it.

The isolation guarantee

Isolation between users is a core design invariant of Nexus, not a configurable setting:

A user can never cause Nexus to resolve another user's credentials — not through a report, not through a pipeline, not through a crafted request, not through assume-role, not in any bridge mode.

This holds structurally, for several reinforcing reasons:

No "whose credentials" parameter exists. Nowhere in the API — not in a report, a pipeline directive, a run request, or an MCP call — is there a field by which a caller names whose credentials to use. Credential resolution always interpolates the authenticated identity taken from the validated token.
Namespaces are separate. Service bridges read only the shared namespace; user bridges read only the caller's own namespace. The two never cross.
Secret names encode the owner. The stored secret name for a user bridge embeds the owner's directory identity, written by the server from validated claims. There is no endpoint that accepts an arbitrary owner segment.
Admins cannot read user values either. Administrators can configure and connection-test service bridges, but cannot read any user's stored bridge values — the secret store never echoes a value back, and no surface resolves another user's namespace. Admin power over the platform does not include reading a colleague's personal credential.
Assume-role doesn't change it. Execution roles grant permissions, not identity, so a run that assumed an elevated role still resolves credentials under its own identity context (see Execution Roles).

Where secrets are stored

All bridge credentials live in your tenant's own Azure Key Vault, inside your Azure subscription. Nexus runs in your tenant, so secrets never leave your boundary and Stingray never holds them. A bridge exists exactly because its secrets exist; deleting the secrets removes the bridge.

Secret names encode scope, owner, bridge, and field so the isolation rules are enforced by structure rather than by convention:

Service default bridge:   <system>.<field>             e.g. mssql.host
Service named bridge:     <system>.<bridge>.<field>    e.g. mssql.production.host
User bridge:              usr.<owner>.<system>.<bridge>.<field>

The <owner> segment of a user bridge is always the caller's directory identity, written by the server from validated claims. Full detail on Key Vault, managed identity, and rotation is on the Secrets Management page.

Adding and testing connections

Service bridges — administrators add, edit, delete, and test connections from the Bridges page. Each bridge type lists its required fields (host, port, credentials, and adapter-specific options), and you can run a connection test before relying on it. Editing service bridges is an administrator action.
My bridges — every user manages their own bridges from the same page, scoped strictly to themselves: list, add a named bridge with its required fields, edit, delete, and test. Nothing a user does here is visible to, or usable by, any other user or any administrator.

When building a report or pipeline, choose the bridge by name and set the bridge mode that matches your governance needs.

Connection governance

A live bridge opens real connections to real databases, and an unbounded system could exhaust a downstream server's connection limit. Nexus applies a connection governor as a defense-in-depth control:

Per-replica connection budget. Each server replica caps how many concurrent bridge connections it will hold, so a burst of pipeline runs cannot open an unbounded number of sessions against your database.
Orphan reaping. Connections left behind by a failed or abandoned run are detected and reclaimed rather than leaking until the database refuses new sessions.
Server-side timeouts. Outbound bridge work is bounded so a slow or hung downstream call cannot pin a connection indefinitely.

This protects your source systems from Nexus itself, which matters when many pipelines and interactive users share a warehouse. It is a resource-safety control, not an authorization control — authorization is always RBAC plus the isolation guarantee above.

Limits & guarantees

Credentials never appear in definitions or history. Reports, pipelines, and their version history contain only bridge names.
Isolation is structural. There is no request shape, mode, or admin power that resolves another user's credentials.
Fail closed, never wider. A missing user identity narrows access to service scope or fails the run; it never falls through to a broader credential.
Governed resource use. The connection governor bounds concurrent connections per replica and reclaims orphans, protecting your source databases.