Provider Bridge¶

The Provider Bridge lets a platform admin load API keys once for the whole organisation. Workspace members pick a model from the standard provider picker and start building, with no key entry and no sign-up with a third-party provider required.

What it is¶

Normally every workspace that wants to use Anthropic, OpenAI, or another provider supplies its own API key (BYOK). The Provider Bridge inverts that: a platform admin registers a provider credential centrally, and the API routes all model calls through that credential on behalf of any user who selects it.

From a user's perspective, bridged providers appear in the model picker with a Platform-managed badge. They work exactly like a personally-keyed provider (same streaming, same tool calling, same model list), except there is nothing for the user to configure.

Why it exists¶

Problem	Bridge solution
New users hit friction setting up API keys before they can try the product	Zero-config first session
Rotating an org-wide key means updating it in every workspace	One credential record to update
Usage visibility across the org	All calls attributed per-user so quotas can be tracked centrally
A user leaving the org	Revoke access without touching individual workspaces

Admin setup¶

1. Open the platform admin panel¶

Navigate to /admin/ai (requires the platform admin role, not just workspace owner).

2. Add a provider credential¶

Click Add provider. Fill in:

Provider type: Anthropic, OpenAI, Google AI Studio, Azure OpenAI, AWS Bedrock, or any other provider in the catalog.
API key: stored encrypted at rest using ENCRYPTION_KEY; never returned to the client in plaintext after saving.
Label: friendly name shown to users (e.g. "Anthropic, org account").
Base URL (optional): override for Azure or self-hosted deployments.

For Azure, you also supply Deployment name and API version.

3. Discover models¶

After saving, click Discover models. Doable calls POST /:workspaceId/ai-settings/providers/:id/discover-models (admin-only endpoint), which:

Queries the provider's model list API.
Caches results in ai_provider_models (keyed by provider_id).
Stores a discoveredAt timestamp in ai_providers.models_cache.

The cached list is what users see in the model picker. Re-run discovery any time the provider adds new models.

4. Enable for workspaces¶

Toggle Available to all workspaces or assign to specific workspaces. Members of enabled workspaces will see the provider in their picker on the next page load.

User experience¶

Workspace Settings → AI → Providers (or the model picker in the editor).
Platform-managed providers appear in a separate Platform-managed group, each with a badge.
Select one. No key or account required.
Set it as the workspace default or choose it per-project.

Per-project selection is stored in workspaces.ai_settings alongside BYOK preferences. Switching back to a BYOK provider at any time is instant.

Security¶

Keys never reach the client. The GET /:workspaceId/ai-settings/providers/:id/models endpoint returns the model list, not the credential. The API key is decrypted server-side only at the moment a model call is dispatched.

Per-user attribution. Every model call carries the user's ID so the platform can track token consumption per user even when the underlying credential is shared. This is the foundation for per-user quota enforcement (quotas UI is a planned follow-up).

Scope isolation. Personal BYOK keys a user stores under their own account (scope = 'user') are invisible to admins and to other users. The Provider Bridge credential operates at scope = 'platform', a distinct scope that cannot be read back via user-facing settings APIs. See Workspaces: personal vs workspace scope for the full scope model.

Encryption. All stored credentials (BYOK and bridge alike) are encrypted with pgp_sym_encrypt using ENCRYPTION_KEY. Rotate that key and re-encrypt credentials if you suspect it is compromised.

Role gating. Only users with the platform_admin flag can create, update, or delete bridge credentials (adminAiRoutes applies platformAdminMiddleware to every request). Workspace admins and members have read-only access to the model list.

Usage dashboards

The backend attribution plumbing is live. Per-user usage dashboards in the admin panel are planned for a follow-up release.

How it differs from BYOK¶

	BYOK	Provider Bridge
Who holds the key	Each workspace or user	Platform admin
Setup per user	Yes, key entry required	None
Key rotation	Per workspace	One place
Usage tracking	Per workspace	Per user, centrally
Visibility to users	User can see their own key (masked)	No key visible at all
Scope	`workspace` or `user`	`platform`