Connection Credentials

Use this reference when setting up an integration or deploying an app that already uses Connect. For a complete first connection, follow Connect Accounts.

Know Which Secret Does What

Connect manages the credentials obtained when someone connects an account. You still register an OAuth app with each vendor whose direct OAuth integration you offer:

• Client ID and client secret: identify your application to the vendor. You obtain them in the vendor console, and Connect reads them from your server environment.
• Access and refresh tokens: authorize a particular connected account. Connect obtains them after consent and encrypts them in your database.
• CLOUDCONFIG_CONNECT_KEY: encrypts those stored account credentials. The CLI generates it, and it stays outside the database.

CloudConfig runs the connection infrastructure in your app. It does not supply a shared OAuth app or create vendor apps for you. You own app registration, consent-screen settings, enabled vendor APIs, and any required vendor review. Users authorize their accounts through your registered app; they do not need to supply its client secret.

Keep Sign-In and Integrations Separate

auth.providers.google lets someone sign in to your app. It defaults to GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and /api/auth/callback/google.

connect.providers.google lets an agent or job act through a Google account. It defaults to CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET, and /api/connect/google/callback. The connected account can differ from the sign-in account, and Google sign-in does not need to be enabled.

Setting up one does not configure the other. GitHub also uses different app types: cloudconfig auth add github guides GitHub OAuth App setup for sign-in; cloudconfig connect add github guides GitHub App setup for integrations.

Set Up Without Prompts

cloudconfig connect add google enables the provider when the CLI can safely edit your config. Without an interactive terminal, or with --no-prompt, it prints instructions instead of collecting vendor credentials.

Supply the printed variables yourself through .env or the process environment. The command can still enable the provider and generate the sealing key. .env.example is a placeholder template, not a credentials file.

A provider without its required credentials is unavailable for OAuth. An API-key fallback, if offered, belongs to your application's integration flow.

Deploy and Maintain Connections

Deploy with cloudconfig deploy. It derives Connect's secret names from the config, requires the sealing key, and uploads provider app credentials when supplied. You do not need to repeat these names in deploy.secrets. Missing provider credentials can leave that provider unavailable without blocking the rest of the deployment.

Keep the sealing key across deployments. Nuxt projects with deploy.automations run bounded housekeeping every five minutes, preserving a sweep cursor between jobs. It refreshes expiring tokens, re-seals connections and registered MCP client secrets after key rotation, and removes abandoned connections. Tune connect.maintenance: { cron, timeZone, limit } (1–500 rows per table per run), or set it to false when another scheduler owns housekeeping. Without an automation host, schedule connect.maintain() yourself. Retain older keys until a full sweep finishes successfully and inspect failed-row counts before removing them. Disconnecting removes a connection and attempts vendor revocation where supported. Connect verifies supported vendor webhooks before handing events to your application. Configure connect.webhooks: { task: 'provider-event' } with an automation host for durable handoff, retry deduplication, and processing after the accepting request ends. Existing onConnectWebhook handlers still execute inline; keep them short. See Deploy Automations for setup and scope checks.

Use .env.example to record names, not values. Keep CLOUDCONFIG_CONNECT_KEY outside the database and preserve it across host changes so existing tokens remain decryptable.