Provisioning a provider connection
Make a provider's OAuth connection work on one tier, with Google as the worked example.
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
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.
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.
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
bun secret1 · Register the redirect URI
On the tier's OAuth client, add this authorized redirect URI:
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:
- Call
GET /api/v2/connectionsas a user of the workspace. Theconnectablelist contains an entry withprovider: "google". The provider appears there only whenavailable()isTrue. The entry'scalendarproduct showsenabled: truewhen the flag is on. - In the boot log of a new Flask task, the line
[ProviderSecrets] google_client_id is unset ...does not appear. POST /api/v2/connections/google/connectwith{"product": "calendar", "return_path": "/"}returns a consenturl.
What a new OAuth provider needs
A provider that follows the same pattern needs:
- A redirect URI. The shared route
/connections/<provider>/callbackserves it. Registerhttps://<host>/connections/<provider>/callbackwith the provider for each tier. - A client id in
app/config/environments.yaml.nullindefaultsmeans not provisioned. The connector'savailable()reads it. - One row per secret in
app/config/provider_secrets.yaml: the provider code, the secret's slug, and the client id key asenabled_by. The SSM SecureString/onramp/<env>/<provider>/<secret>, the committed Pulumi secretprovider<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 withprovider_secret(provider, secret)fromapp/api/connections/provider_secrets.py. - 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. - A flag row. A migration inserts a
featuresrow for the provider's product.provider_enabledinapp/api/calendars/registry.pyreads it.migrations/versions/2026_11_06_5b535abd1019_add_provider_connections.pyis the reference.
Troubleshooting
provider_not_provisionedgoogle_client_id is null for the tier. Set it in the config map (step 2) and deploy.
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 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.
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.