Connector OAuth — platform setup

Connectors are OAuth-first: providers with an OAuth flow show a one-click connect button when the platform credentials below are configured (secrets on the kordox-api worker). Without them the UI falls back to guided manual entry where one exists, or shows a "not enabled on this workspace" state.

Provider matrix

Provider	Secrets	Notes
Stripe	STRIPE_CLIENT_ID (+ STRIPE_SECRET_KEY for token exchange)	Restricted-key path always available too; OAuth grant is read-only — see below
Shopify	SHOPIFY_CLIENT_ID (+secret)	Needs shop domain pre-redirect
Meta Ads	FACEBOOK_APP_ID + FACEBOOK_APP_SECRET
Google Ads	GOOGLE_ADS_CLIENT_ID + GOOGLE_ADS_CLIENT_SECRET + developer token
HubSpot	HUBSPOT_CLIENT_ID (+secret)
Salesforce	SALESFORCE_CLIENT_ID (+secret)
GCP Billing	GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET (main Google app)	See below
Gmail / Google Calendar	same main Google app
Outlook / MS Calendar	Azure app	See email-oauth

Stripe specifics

The Stripe OAuth flow is Stripe Connect (Standard accounts) — the connected party keeps their own Stripe dashboard, payouts and dispute liability; money settles in their account, and Kordox takes no application fee. This is only the revenue-sync path; it is not required for getting paid — invoices and paid bookings use the org's own restricted API key (Checkout Sessions: Write), which is unaffected.

One-time platform setup (in Kordox's own Stripe dashboard — cannot be done via the Stripe CLI or API; the ca_… client ID is dashboard-only):

1. Enable Connect and complete the platform profile.
2. Under Settings → Connect → Onboarding options / OAuth, register the redirect URI: https://api.kordox.com/api/oauth/stripe/callback (staging: https://api-sta.kordox.com/api/oauth/stripe/callback).
3. Copy the OAuth client ID (ca_…) and set it as the worker secret STRIPE_CLIENT_ID. Token exchange authenticates with STRIPE_SECRET_KEY (the platform's own key), which is already set for SaaS billing.

The requested scope is read_only (stripe.tsgetOAuthUrl), so the resulting token can read charges/payouts/balance for P&L sync but cannot create Checkout Sessions. If a write-capable connect flow is ever needed, bump the scope and re-register.

GCP Billing specifics

Rides the main Google OAuth app (same as login/Gmail) with scopes cloud-billing.readonly + bigquery.readonly.

Required one-time setup on the Google Cloud project that owns the OAuth client (currently kordox, client 756638925848-…):

1. Authorized redirect URI: https://api.kordox.com/api/oauth/gcp-billing/callback.
2. Enable APIs on that project — user-token API calls authorize against the OAuth client's project, so these must be on even though the DATA lives in the customer's project:
   • cloudbilling.googleapis.com (Cloud Billing API)
   • bigquery.googleapis.com (BigQuery API) A disabled Cloud Billing API surfaces in the connector card as "Cloud Billing API is not enabled on the platform's Google project".

The OAuth callback runs auto-discovery (GcpBillingConnector.discover): lists the user's billing accounts (auto-picks a single open one) and scans BigQuery for a gcp_billing_export_v1_* table. The Re-detect from Google button on the connector card re-runs it any time (POST /api/financial/accounts/:id/rediscover) — it fills only empty fields, and an explicit user pick always wins.

Google verification (before external signups)

cloud-billing.readonly, bigquery.readonly, and the Gmail scopes are sensitive/restricted — external users cannot consent until the Google OAuth app passes verification review. Owner + test users work immediately. Start the review well before opening signups; it takes weeks and is required once per app, not per scope addition thereafter.