Authentication

Each client project MUST have its own Clerk application.

The application is the user-pool boundary: two applications share no users, sessions, or sign-ins. That boundary is what client isolation means here. Applications are unlimited and each carries its own free tier, so cost is never a reason to merge two clients into one.

Satellite domains and Organizations MUST NOT be used to separate clients.

Both features exist to share one user pool — satellite domains give one login across many domains, Organizations give many tenants inside one application. Using either for isolation achieves the exact opposite of the intent, and the failure is invisible until a client sees another client's user.

A production deployment MUST use a Clerk production instance.

A development instance uses Clerk's shared OAuth credentials, has stricter rate limits, and sends email from accounts.dev. It is for local development. The publishable key decodes to the frontend API host, so which instance a deployment is running is checkable rather than assumed.

echo "${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY#pk_live_}" | base64 -d
# a *.clerk.accounts.dev result means this is a DEV instance

A production instance MUST NOT use the bare root domain as its instance domain.

Setting it to the root shares sessions across every subdomain, which re-couples the clients that separate applications were created to isolate. Use the client's own subdomain.

Clerk DNS records MUST NOT be proxied.

A proxied CNAME — Cloudflare's orange cloud and equivalents — breaks domain verification. The symptom is a verification that never completes, which reads as a Clerk fault rather than a DNS setting.

Social sign-in in production MUST use the project's own OAuth credentials.

Development shares Clerk's credentials and they do not carry over. Shipping with social login enabled and no custom credentials produces sign-in buttons that simply fail, and they fail only in production.

A Microsoft application registration MUST be multitenant.

Single-tenant registration means users in an external client's directory cannot sign in at all. Since every client here is an external organisation, single tenant is always wrong.

A Google OAuth application MUST be published before production use.

An application left in Testing publishing status admits one hundred users and then stops, silently, partway through a rollout.

An OAuth client secret MUST have a recorded expiry and renewal owner, per STD-007 §3.9.

Microsoft client secrets expire. The outage is total, arrives without warning, and looks like an application fault rather than a calendar one.

An OAuth client identity published as a Client ID Metadata Document MUST be an HTTPS URL with a path component, on an apex the organisation controls, and the document's client_id MUST equal that URL exactly.

The URL is the client's identity: every authorization server that ever granted a consent against it will fetch, display, and trust it. A URL on a domain we might lose, or one whose client_id drifts from its address, invalidates consents in a way no rotation procedure recovers.

A Client ID Metadata Document MUST be hosted by the product that owns the client, at a URL of that product's choosing, and the product MUST keep the document reachable for as long as any consent granted against it remains live. A shared organisation-wide registry site MUST NOT be the host.

Decided in umwelten ADR 0020 after considering central hosting: client identity is decoupled from any single deploy pipeline, so no one site outage or migration can strand every OAuth client in the organisation at once. The accepted cost is that there is no single place to audit all client documents — discovery is per-product.

A new integration SHOULD register via Client ID Metadata Documents when the authorization server advertises support (client_id_metadata_document_supported), falling back to Dynamic Client Registration only where it does not; and client credentials obtained by registration MUST be stored keyed by the issuing authorization server and MUST NOT be reused across issuers.

DCR is deprecated in the MCP authorization spec [4] and survives only as a compatibility path. Credentials keyed by server URL rather than issuer collide the moment a resource changes authorization servers — the failure is silent until a token from the wrong issuer is refused in production.