Documentation

Provider connections guide

Customers open a website's Settings → Integrations, authorize their provider, and choose an accessible repository or ad account. Search Console finds the matching property from the saved website domain automatically. Owners and admins manage connections; viewers cannot start or complete authorization.

Provider apps belong to the AnalyticFast operator. Customers do not register OAuth apps or paste platform secrets for quick connections. Existing customer-owned credential setup remains under Connect with access token. When an operator app is not configured, its quick-connect button is hidden and only the access-token setup is shown. GitHub App and Meta quick connections require a hosted user account; self-hosted password installations retain manual setup.

Google Search Console

Use the existing Google sign-in client and callback {APP_ORIGIN}/api/auth/google/callback. Signed GSC state dispatches to a separate handler, preserving the current AnalyticFast login. Existing signed flows using /api/gsc/callback still complete with their original redirect URI.

Enable the Google Search Console API in the Google Cloud project and configure the OAuth consent audience for https://www.googleapis.com/auth/webmasters.readonly. The operator's existing GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, SESSION_SECRET and PROVIDER_ENCRYPTION_KEY secrets are reused. API enablement and consent/publishing are Google-side settings and are not established by the presence of Worker secrets.

When the audience is External/Testing, allow the relevant test users. Google's refresh tokens for non-identity scopes in Testing generally expire after seven days; publish and complete any required Google verification for a production customer rollout. Google web-server OAuth, token expiry.

After consent, AnalyticFast lists the account's accessible properties, rejects unverified/unrelated properties, and chooses the closest match. Covering parent-domain properties are permitted, with Search Analytics requests and imported rows restricted to the saved website hostname and its www alias. Query revenue remains an estimate. No property is created or verified on the customer's behalf.

GitHub App

Register an operator-owned public GitHub App with:

• Homepage: the AnalyticFast app origin.
• User authorization callback: {APP_ORIGIN}/api/connect/github/callback.
• Setup URL: {APP_ORIGIN}/api/connect/github/installed.
• Repository permissions: Contents: read-only, Metadata: read-only. No write, organization or account permissions are needed.
• Installation on selected repositories. Disable “Request user authorization (OAuth) during installation”; AnalyticFast starts a separate authorization flow before installation.
• Webhooks can stay inactive; commits are polled.

Configure Worker secrets GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET and GITHUB_APP_PRIVATE_KEY. Use the App's actual generated private key. Never commit these values.

The callback's installation ID is not proof of ownership. AnalyticFast checks the signed-in GitHub user's accessible installations and repositories before allowing a selection. Each sync mints a short-lived installation token restricted to the selected repository and read-only permissions. Persistent site credentials contain the encrypted installation ID, rather than a customer's long-lived personal token.

Official references: register an App, setup URL and ownership checks, installation tokens.

Meta Ads

Create an operator-owned Meta developer app with Facebook Login for Business and a login configuration that issues USER access tokens with ads_read. Do not choose system-user or non-expiring tokens; this connection flow requires a user grant with an expiry. Configure the valid OAuth redirect {APP_ORIGIN}/api/connect/meta/callback. Enable the appropriate live mode, business verification and approved/advanced access for customer businesses as required by Meta.

Configure Worker secrets META_APP_ID, META_APP_SECRET and META_LOGIN_CONFIG_ID. Do not request ads_management for reporting. Customers choose an ad account returned by their authorized account; arbitrary ad-account IDs cannot be submitted as a substitute for access.

Authorization exchanges and long-lived tokens remain server-side. Grants are encrypted, have an expiry, and include app-secret proof for Graph requests. Expired or revoked access requires reconnecting; AnalyticFast does not silently claim that a saved token is valid. Imports remain read-only, with existing spend/currency and attribution rules.

Official references: Facebook Login for Business, long-lived tokens, Marketing API. Current implementation comments cite the maintained official SDK where documentation was rate-limited.

X and Reddit monitoring

These integrations search public mentions rather than reading a connected customer's private account. Setup suggests the saved website name and keeps access instructions behind an expandable section. X developer access/credits and Reddit's API approval/commercial requirements still apply; a login button cannot replace them. Existing explicit opt-in for recurring metered X requests is preserved. See [monitoring setup](marketing.md).

Security and availability

Quick-connect buttons are unavailable until their operator app is configured. A configured Worker does not prove provider-side app approval, consent, API enablement or successful live authorization. Setup requires a successful connection and sync to verify those external prerequisites.

Authorization state and picker grants expire after ten minutes, bind the current browser user, site and provider, and are single-use. Only state hashes and encrypted temporary grants enter D1. Provider tokens are never returned to the browser. Hourly maintenance removes expired/used grants; account/site deletion cascades to pending state. Every callback and selection rechecks current site administration rights.