Clients

Clients are applications that use DarkAuth for authentication or authorization. A client controls how an app redirects users, exchanges codes, receives tokens, requests scopes, and optionally participates in zero-knowledge key delivery.

Public clients

Public clients cannot keep a secret. Browser apps, native-style apps, and many frontend-only apps should be configured as public clients. They use Authorization Code with PKCE and token_endpoint_auth_method set to none.

Require PKCE for public clients. PKCE protects against authorization code interception by binding the code exchange to a verifier generated before the redirect.

Confidential clients

Confidential clients can protect a client secret server-side. They use client_secret_basic at the token endpoint and can support server-side web apps, support tools, or backend services.

Generated client secrets are shown only when a confidential client is created or when a write admin rotates the secret. Later reads never reveal the same plaintext secret. Store generated client secrets in a secret manager immediately.

Rotate a client secret when it may have been exposed, when a deployment process needs a new value, or as part of normal credential hygiene. Rotation returns the new plaintext secret once.

Redirect URIs

Redirect URIs should be exact and boring. Avoid broad patterns, wildcard domains, and user-controlled origins. A redirect URI is where DarkAuth sends authorization results, so mistakes here can become account takeover paths.

Register separate clients for materially different apps or environments. A production app, staging app, and local dev app often deserve separate client records.

Scopes and descriptions

Scopes describe what the client is asking for. Built-in scopes such as openid, profile, and email are common, and clients can also request custom scopes. Provide useful descriptions so the consent screen explains the request in language a user can understand.

ZK delivery settings

Zero-knowledge key delivery is opt-in per client. Current v2 clients receive a client app key, while explicit legacy v1 clients can still receive the older root-key delivery. Only enable fragment-jwe for applications that are designed to handle encrypted key material safely, verify the delivery binding, and manage plaintext key custody deliberately.

Do not enable ZK delivery because it sounds stronger. Enable it because the application has a real client-side encryption model and a clear recovery story.

Key delivery versions

New ZK clients should use:

• key_delivery_version: "v2"
• delivered_key_kind: "client_app_key"

The v2 flow derives a Client App Key, or CAK, for the requesting client and organization context. The application receives only that client-scoped key, not the user’s account root key.

Legacy clients that already depend on the older root-key handoff can be kept on:

• key_delivery_version: "v1-drk"
• delivered_key_kind: "root_key"

Do not change a production encrypted app from v1 to v2 until the application has shipped migration logic. Existing encrypted data may have been written under keys derived from the legacy delivery model.

Migration guidance

A safe v1-to-v2 migration usually has four phases:

1. Ship application code that can read legacy data and write new data under a v2 client app key.
2. Enable v2 key delivery for the DarkAuth client.
3. Rewrap or re-encrypt existing application data under the v2 key hierarchy.
4. Remove legacy-read support after active data and users have moved.

During the migration, watch authorization and token errors for hash mismatches, missing fragments, stale callback state, and unexpected legacy clients. Those usually mean the app and DarkAuth client settings are out of sync.

Admin visibility

Admins can see whether ZK delivery is enabled, which delivery version a client uses, and whether the client receives a root key or client app key. Admins cannot see plaintext delivered keys, user account root keys, OPAQUE export keys, recovery keys, passkey PRF output, or fragment JWE payloads.