Connect Accounts

An app that reads someone's Gmail needs permission to use their Google account. CloudConfig Connect handles the consent callback, encrypted tokens, refreshes, and connection ownership inside your application.

This guide assumes sign-in is working. Your application supplies the integration UI and decides which actions an agent or job may run. The example requests permission to read and modify Gmail messages.

1. Declare the Google Permissions

Add a connect block to your existing cloud.config.ts:

connect: {
  providers: {
    google: {
      scopes: ['https://www.googleapis.com/auth/gmail.modify'],
    },
  },
},

These permissions are for an integration. Google does not also need to be your sign-in provider; a connected account can differ from the sign-in account.

2. Register Your OAuth App

Run the setup command:

pnpm exec cloudconfig connect add google

The command prints the vendor console link, scopes, and callback URLs. Keep it open while you complete the Google setup:

1. Create an OAuth web application in the linked console.
2. Configure its consent screen and enable the Gmail API.
3. Register the callback URL printed by the CLI.
4. Copy the client ID and secret, then paste them into the terminal prompts.

The default local callback is:

http://localhost:3000/api/connect/google/callback

Setup writes CONNECT_GOOGLE_CLIENT_ID and CONNECT_GOOGLE_CLIENT_SECRET to the ignored .env file. It also generates CLOUDCONFIG_CONNECT_KEY, which encrypts stored account tokens. You register the vendor app; Connect does not supply a shared OAuth app.

For CI or non-interactive setup, see credentials.

3. Create the Connection Tables

Generate and apply migrations, then inspect the settings:

pnpm db:generate
pnpm db:migrate
pnpm exec cloudconfig connect status

Restart the app to load environment changes. status reports missing local settings and callback URLs; it does not test credentials with Google.

4. Connect an Account

Start the flow from your application's browser UI:

import { createConnectClient } from '@cloudconfig/core/client'

const connect = createConnectClient()
await connect.connect('google', { scope: 'user' })

The user grants access at Google. Connect stores encrypted tokens and returns the browser to the starting page with ?connect=connected&connection=<id>.

In Nuxt, useCloudConfigConnect() provides the browser client.

Use the Account on the Server

Server code calls connect.access(actor, connectionId) to obtain a usable token. Connect checks ownership and organization membership, then refreshes an expiring token when supported. In Nuxt, obtain the server API with useCloudConfigConnectServer(event).

Personal connections belong to their owner. Workspace connections are usable by current organization members and managed by owners and admins by default; enable auth.organizations when your app needs workspaces.

Keep tokens out of browser responses and feature records. Store the connection ID and non-secret settings with a feature, then resolve the token on the server.

Next, read Deploy and Maintain Connections when deploying, or Connect MCP Servers when your server needs tools from a hosted MCP service.