Multi-tenant auth for customer-facing integrations

Multi-tenant auth for customer-facing integrations means storing and refreshing a separate OAuth credential for every one of your customers’ third-party accounts. Each tenant needs isolated token storage, independent refresh cycles, and per-tenant scope enforcement — so one customer’s expired Salesforce token never affects another’s. Every customer who signs up for your product wants to connect their own Salesforce, Slack, or Google Drive account to it, and none of them can be allowed anywhere near another customer’s tokens. Multiply that by a few hundred accounts: each one needs its own OAuth flow started, its own credential issued, stored, refreshed on its own schedule, and revoked the moment that customer disconnects, without a single token ever leaking sideways into someone else’s session.

Underneath that is the scale problem multi-tenant authentication actually solves: N customers × M third-party apps means N×M live credentials, not N+M, each refreshed, expired, and revoked on its own. What follows covers that end to end: the OAuth flows and specs that govern a connection, how tokens get stored, managed, and refreshed at scale, and where a platform absorbs that work versus what you’d still build.

TL;DR

• The scale problem is N×M, not N+M. Every customer needs a separate credential for every third-party app, each issued, refreshed, and revoked on its own clock.

• Default to a PKCE-secured authorization code grant. RFC 6749 defines the grant, PKCE is its own spec, and RFC 9700 makes PKCE a MUST for public clients and a RECOMMENDED for confidential ones. The implicit grant is discouraged, not forbidden.

• The state parameter is no longer the automatic answer to CSRF: OAuth 2.1 treats it as optional where PKCE or an OIDC nonce covers the same ground, and only once you have confirmed the authorization server supports it.

• Each completed flow produces its own encrypted Credential, distinct per end user, resolved at request time rather than shared across your tenant base.

• The Paragon User Token carries sub, iat and exp, and an audience scoped to your project, signed with a key you generate in the dashboard.

• Get the isolation model or the encryption wrong and a single breach reaches every tenant in the store rather than one, which is what makes token storage the highest-stakes decision here.

• Two rhythms run underneath: once per end user at connect time, then on every request afterward.

• Refresh is the hardest part to keep correct. Rotation retires the previous token on each exchange, two workers refreshing at once can leave a retired token trusted, and every provider sets its own caps and expiry rules.

• All of it is buildable in-house. What changes is who owns keeping it correct through each provider’s next policy change.

• Against Nango, Composio, Workato Embedded, Auth0 Token Vault and WorkOS Pipes, isolating credentials per tenant is now something most funded platforms do; the separation is the connector, actions and sync layer sitting on top of it.

• Paragon runs this as Connect Portal, a white-labeled auth screen embedded with one SDK call, plus the Paragon User Token: an RS256-signed JWT your own server issues, not Paragon’s.

What multi-tenant auth actually means

A single-tenant OAuth integration is simple: one app, one set of credentials, one token to refresh. A customer-facing integration multiplies that by every end user — you define “connect to Salesforce” once but authorize it once per customer, and N customers × M third-party apps means N×M live credentials in storage, not N+M. A few hundred customers each connecting two or three apps isn’t a few hundred credentials; it’s several times that, each refreshing, expiring, and getting revoked on its own schedule.

OAuth 2.0 (RFC 6749) is the authorization framework underneath it all — the client, resource owner, resource server, and authorization server roles, and the grant exchanging a user’s consent for a token. OIDC sits on top as a separate, optional identity layer, adding a signed ID token answering “who is this user” rather than just “can this client access this resource.” A multi-tenant platform needs OAuth regardless; it only needs OIDC if it’s also asserting who’s connecting.

Concretely: a distinct credential per end user rather than one shared app-level token, refresh on each credential’s own schedule, mapping a request to the right credential before any API call goes out, and clean revocation on disconnect without touching anyone else’s. Get one wrong and you’ve built a data-isolation bug into your product — see the operational challenges of building this yourself.

The OAuth flows and the specs that govern them

Third-party OAuth flows for a multi-tenant integration default to a PKCE-secured authorization code grant; the implicit grant is now dead. RFC 6749 defines that grant and its original state parameter; PKCE is a separate spec. RFC 9700 — the OAuth 2.0 Security Best Current Practice — governs a compliant flow today, PKCE included, with the state parameter load-bearing. OAuth 2.1 folds much of this together but remains an Internet-Draft, not a ratified standard. The full spec breakdown covers each requirement. Provider setup: Jira, Slack, Salesforce.

Token storage and tenant isolation

Once a credential exists, storing it safely is the next problem: get the isolation model or the encryption wrong, and one breach reaches every tenant in that store, not just one. Paragon’s own credentials follow that same discipline, vaulted and Paragon-managed. A deeper look at multi-tenant OAuth architecture works through the isolation models, the token record schema, and the key-rotation mechanics that make token management trustworthy at scale.

Where authorization ends and the rest of your integration begins

Two rhythms make up this flow: what happens once per end user, and what happens on every request after that.

Once, when a user connects: your app embeds Connect Portal with a single SDK call, the user completes the OAuth flow for the third-party app, and Paragon stores that authorization as a per-user Credential, encrypted at rest.

On every request after that: your app passes a signed Paragon User Token naming which end user it’s acting on behalf of, Paragon resolves that specific user’s Credential and never a different one, and refresh and revocation happen on that Credential without your backend tracking expiry windows or storage itself.

What your integration does with that access, which CRM records it reads or writes, or what it syncs into your own pipeline, is a separate layer on top of this one: see connecting your SaaS to Salesforce and HubSpot for the CRM case and syncing customer data into a vector database for ingestion, and keeping RAG data fresh with incremental sync and deduplication for how that ingested data stays current. The same identity model underlies agent-facing integration setups, where a tool call needs to resolve to one user’s data and no one else’s. This article stops at authorization: the right user authenticated, isolated, and resolvable, before any action or sync runs.

Refresh, rotation, and token expiry at scale

Refresh is the hardest part of multi-tenant OAuth to keep correct at scale: refresh token rotation issues a new token on every exchange and retires the last one, and two workers refreshing at once can leave a rotated-out token trusted by mistake. Every provider runs its own cap and rotation policy, so the failure mode that shows up isn’t one bad token — it’s a refresh storm, tokens hitting a provider’s endpoint in a correlated burst. More on the concurrency fix and provider-by-provider policy quirks covers what breaks at volume.

How Paragon handles multi-tenant auth for customer-facing integrations

Paragon is the pick for teams that need a ready-made, white-labeled auth screen their own customers can use across Paragon’s hundreds of pre-built connectors, backed by a documented per-user token their backend can verify, rather than a bare API they’d have to wrap in a UI themselves. Connect Portal handles the OAuth screen and branding; the Paragon User Token, an RS256-signed JWT your server issues with sub, iat, exp, and aud claims, ties each session to one specific end user; and every credential that comes back from that flow is stored as an isolated Credential object, encrypted in transit and at rest, that only resolves for the user it belongs to. Together, those three pieces are a multi-tenant auth layer built to scale to thousands of end users without a shared credential ever crossing accounts.

How Paragon isolates credentials per end user

Every time a user completes the auth flow, Paragon stores their third-party credential as its own Credential object, distinct from every other user’s, encrypted both in transit and at rest. That object is what Paragon resolves against when your app makes a request on that user’s behalf, and it’s what gets revoked or re-authorized without touching any other user’s connection.

Users aren’t limited to one account per integration, either. Multi-Account Authorization lets a single end user attach more than one account for the same integration, two separate Google Drive accounts, for instance, each stored as its own Credential with its own ID. That matters for a customer who manages more than one third-party workspace and needs your product to address a specific one, not just “whatever they connected first.”

The Paragon User Token, explained

The mechanism that ties a request to the right Credential is the Paragon User Token: an RS256-signed JWT that your application server signs, not Paragon. You generate a private signing key from the Paragon dashboard under Settings, sign a token containing sub (your user’s or organization’s ID), iat, and exp, plus an aud claim formatted as useparagon.com/{project-id}, and Paragon verifies that signature against the matching public key before it will resolve any Credential for that session. Your backend never hands Paragon a shared API key that covers every user; it hands Paragon a token scoped to exactly one.

The Connect SDK’s .authenticate() method is called at the start of your app’s session so the token stays current while the user is active, and the same token authorizes both the Connect Portal auth screen and any subsequent API or MCP session tied to that user. One signed claim, reused everywhere Paragon needs to know whose data it’s touching, replaces separate credential stores for a UI flow, a REST call, and an agent session, including agents built to integrate external data on a user’s behalf.

The embedded auth experience (Connect Portal)

Most teams don’t want to design and maintain their own OAuth consent screens for every third-party app they support, and they don’t want customers redirected to a generic, unbranded authorization page either. Connect Portal solves both with a single SDK call: it renders a white-labeled auth experience under your own domain, and it’s the same UI your customers use whether they’re connecting Salesforce, Slack, or any of Paragon’s hundreds of pre-built connectors. Full removal of Paragon branding is a paid-plan feature, but the embed itself, with your customer completing the flow inside your product instead of a third-party page, is the default.

That single embed point is also where the isolation model above becomes visible to your users: each person who runs through Connect Portal gets their own Credential, tied to their own Paragon User Token, and can disconnect or reconnect their account without any visibility into or effect on anyone else’s.