Skip to content

Provisioning a provider connection ​

Make a provider's OAuth connection work on one tier, with Google as the worked example.

Owner: PlatformWhen to use: turning on a connection provider for a tierWorked example: Google (calendar-google)

Canonical sources. The callback route is app/api/connections/routes.py. The Google connector and its availability check are in app/api/connections/providers/google/connector.py. Each provider secret is one row in app/config/provider_secrets.yaml. Flask reads that row in app/api/connections/provider_secrets.py, which holds the boot check. The infra reads it in infra/components/provider-secrets.ts, and infra/app/provisioned-params.ts derives the boot-fatal declaration from it. The secret script is infra/app/secret.ts. This runbook is the HOWTO. Those files are the truth.

TL;DR ​

🅰 Four things per tier

A redirect URI, a client id, a client secret, and a flag. Until the client id is in the config map, the provider reports itself unavailable and nothing else runs.

🅱 One PR, no deploy order

The client id and the committed secret land in the same PR. The deploy gate refuses to roll a tier whose boot-fatal secret is missing, so no release has to land before another.

🅲 Check with one GET

GET /api/v2/connections lists the provider under connectable once the client id is set. The calendar product shows enabled: true once the flag is on for the workspace.

The procedure ​

1
Redirect URI
Google Cloud console
2
Client id
config map
3
Boot-fatal secret
Pulumi
4
Seed the secret
bun secret
5
Flag
per workspace

1 · Register the redirect URI ​

On the tier's OAuth client, add this authorized redirect URI:

text
https://<host>/connections/google/callback

<host> is the tier's public host. The route is GET /connections/<provider>/callback, declared in app/api/connections/routes.py. The connect request builds the URI it sends to Google from the app's CANONICAL_PUBLIC_BASE_URL. If that value is unset, it uses the request host. Google refuses the consent screen when the URI sent does not match a registered one exactly.

Register one URI for each tier that serves workspaces. Each tier has its own host.

Verify ​

Until the client id is set, available() returns False, the boot check logs [ProviderSecrets] google_client_id is unset for this environment, skipping the boot check for '/onramp/<env>/google/client_secret'., and a connect request returns the error code provider_not_provisioned.

After steps 2 to 4 have deployed and step 5 is done:

  1. Call GET /api/v2/connections as a user of the workspace. The connectable list contains an entry with provider: "google". The provider appears there only when available() is True. The entry's calendar product shows enabled: true when the flag is on.
  2. In the boot log of a new Flask task, the line [ProviderSecrets] google_client_id is unset ... does not appear.
  3. POST /api/v2/connections/google/connect with {"product": "calendar", "return_path": "/"} returns a consent url.

What a new OAuth provider needs ​

A provider that follows the same pattern needs:

  1. A redirect URI. The shared route /connections/<provider>/callback serves it. Register https://<host>/connections/<provider>/callback with the provider for each tier.
  2. A client id in app/config/environments.yaml. null in defaults means not provisioned. The connector's available() reads it.
  3. One row per secret in app/config/provider_secrets.yaml: the provider code, the secret's slug, and the client id key as enabled_by. The SSM SecureString /onramp/<env>/<provider>/<secret>, the committed Pulumi secret provider<Provider><Secret>, the boot-fatal member, the web Lambda's read access and the boot check all derive from that row. The connector reads the value with provider_secret(provider, secret) from app/api/connections/provider_secrets.py.
  4. The parameter name in the test. Add the literal parameter name to the tier's list in infra/app/provisioned-params.test.ts, under the same condition on the client id.
  5. A flag row. A migration inserts a features row for the provider's product. provider_enabled in app/api/calendars/registry.py reads it. migrations/versions/2026_11_06_5b535abd1019_add_provider_connections.py is the reference.

Troubleshooting ​

🚫 Connect returns provider_not_provisioned

google_client_id is null for the tier. Set it in the config map (step 2) and deploy.

⚠ Google shows redirect_uri_mismatch

The registered URI does not match the one the app sent. Compare the registered value with https://<host>/connections/google/callback for the host the user is on.

🚫 The Committed Secrets check fails the PR

The PR sets google_client_id but does not commit providerGoogleClientSecret for every stack that reads it. Run bun secret on the PR's branch (step 4) and push.

⚠ Flask fails at boot with "Provider secret is unavailable"

The SSM parameter named in the message does not exist or is unreadable on that tier. Check that the infra apply created /onramp/<env>/google/client_secret.

Internal documentation — gated behind Cloudflare Access.