Connecting Clients

Overview

Before generating reports, you need to:

Add a client record with their website details
Connect their Google account via OAuth
Select their Search Console property and Analytics property

This guide covers the complete client setup workflow.

Prerequisites

Google APIs configured
An active Reportr subscription (or trial)
Google account with access to client’s Search Console and Analytics

Client Limits by Plan:

Free: 1 client
Starter: 5 clients
Professional: 15 clients
Agency: 50 clients

See /workspace/source/src/lib/plan-limits.ts:15-43 for plan limits.

Step 1: Add a New Client

Navigate to Clients page

From your dashboard, click Clients in the sidebar or navigate to /dashboard/clients

Click 'Add Client'

Click the Add Client button in the top right corner.

If you’ve reached your plan’s client limit, you’ll see an upgrade prompt instead. See the error message for your current usage.

Fill in client details

Required fields:

Client Name: The client’s business name (min 2 characters)
Website URL: Full URL including https:// (must be valid URL format)

Optional fields:

Contact Name: Client’s primary contact person
Contact Email: Valid email address for the client

The website URL must match the domain verified in Google Search Console.

Save the client

Click Create Client. The client will be created with a unique ID and appear in your clients list.

Step 2: Connect Google Account

Start OAuth flow

After creating the client, click Connect Google Account on the client card.Alternatively, click the client name → Settings → Connect Google Account

Authorize Google access

You’ll be redirected to Google’s OAuth consent screen. Review the permissions:

Google Search Console - Read-only access to search analytics
Google Analytics - Read-only access to Analytics data

Click Allow to grant access.

The OAuth flow is handled by /workspace/source/src/app/api/auth/google/authorize/route.ts and the callback is processed at /workspace/source/src/app/api/auth/google/callback/route.ts

Verify connection

After authorization, you’ll be redirected back to the Clients page with a success message.The client card will now show:

✅ Google account connected
Green “Connected” badge
Connection timestamp

What Happens During OAuth?

When you authorize Google access, Reportr:

Requests OAuth scopes (see /workspace/source/src/lib/google/config.ts:3-6):

'https://www.googleapis.com/auth/webmasters.readonly'
'https://www.googleapis.com/auth/analytics.readonly'

Receives tokens from Google:
- Access token (expires in ~1 hour)
- Refresh token (used to get new access tokens)
Stores encrypted tokens in your database:
- googleAccessToken - Current access token
- googleRefreshToken - Long-lived refresh token
- googleTokenExpiry - When access token expires
- googleConnectedAt - Connection timestamp
Automatically refreshes access tokens when they expire using the refresh token logic in /workspace/source/src/lib/google/config.ts:16-32

Step 3: Select Search Console Property

View available properties

After connecting Google, click Configure Properties on the client card.Reportr will fetch all Search Console sites accessible with your connected Google account.

Choose the correct site

Select the Search Console property that matches your client’s domain:

https://example.com - HTTPS site
http://example.com - HTTP site
sc-domain:example.com - Domain property (recommended)

Domain properties include all protocols and subdomains. Use these when available for complete data.

Save Search Console configuration

Click Save to store the selected property. This updates the client record with:

gscSiteUrl - The property URL identifier
gscSiteName - Display name for the property

Step 4: Select Analytics 4 Property

View GA4 properties

In the same configuration screen, Reportr will list all Google Analytics 4 properties you have access to.

Only GA4 properties are shown. Universal Analytics (UA) properties are not supported.

Select the client's property

Choose the GA4 property that corresponds to this client’s website.Properties are listed with:

Property name
Property ID (e.g., properties/123456789)

Save Analytics configuration

Click Save to complete the setup. This stores:

ga4PropertyId - The GA4 property identifier
ga4PropertyName - Display name

Verification

After completing the setup, verify the client is properly configured:

Check connection status

On the Clients page, the client card should show:

✅ Google Connected
✅ Search Console Configured
✅ Analytics Configured

Test data fetching

Click Generate Report on the client card.If everything is configured correctly:

Report generation will start
You’ll see “Processing” status
Data will be fetched from both APIs

Managing Multiple Clients

Using Different Google Accounts

If your clients use different Google accounts for their properties:

Shared account approach (recommended):
- Have clients grant you Editor access to their Search Console and Analytics
- Connect all clients using your agency’s Google account
- Benefit: Single login, easier management
Individual account approach:
- Disconnect the current Google connection
- Re-authorize with a different Google account for each client
- Limitation: You need to re-authenticate when switching between clients

Bulk Client Setup

For agencies with many clients:

Prepare client list

Create a spreadsheet with:

Client names
Website URLs
Contact information
Search Console property URLs
GA4 property IDs

Add clients sequentially

Use the UI to add clients one by one, or use the API endpoint:

POST /api/clients
Content-Type: application/json

{
  "name": "Client Name",
  "domain": "https://example.com",
  "contactName": "John Doe",
  "contactEmail": "[email protected]"
}

See /workspace/source/src/app/api/clients/route.ts:18-95 for the implementation.

Connect Google once

If all clients share the same Google account access, you only need to connect once and select different properties for each client.

Troubleshooting

”Client not found or unauthorized”

Problem: Cannot access a client you created Solution:

Ensure you’re logged in with the same account that created the client
Clients are isolated by user ID for security
Check database for userId matching in the clients table

No Search Console Sites Found

Problem: Property list is empty after connecting Google Solution:

Verify the connected Google account has Search Console access
Check that sites are verified in Google Search Console
Grant your Google account Owner or Full User permission
Wait 24 hours after adding a new site to Search Console

Wrong Analytics Property Listed

Problem: Can’t find the correct GA4 property Solution:

Confirm the property is GA4, not Universal Analytics
Verify your Google account has at least Viewer access to the property
Check Google Analytics to confirm property exists
Properties may take time to appear after being created

Token Refresh Failures

Problem: “Google account not connected” error after initial connection Solution:

Refresh tokens can expire if:
- User revokes access in Google Account settings
- App is removed from authorized apps
- Refresh token hasn’t been used for 6 months
Fix: Disconnect and reconnect the Google account
Reportr automatically attempts token refresh (see /workspace/source/src/lib/google/config.ts:16-32)

“Email verification required”

Problem: Cannot add clients despite being logged in Solution:

Free plan users must verify their email before adding clients
Check your inbox for verification email
Paid subscription users bypass this requirement
See the check in /workspace/source/src/app/api/clients/route.ts:23-39

Client Data Schema

For reference, here’s what’s stored for each client (from /workspace/source/prisma/schema.prisma:73-108):

Field	Type	Description
`id`	String	Unique client identifier
`name`	String	Client business name
`domain`	String	Client website URL
`contactEmail`	String?	Contact email (optional)
`contactName`	String?	Contact name (optional)
`googleRefreshToken`	String?	OAuth refresh token (encrypted)
`googleAccessToken`	String?	Current access token (encrypted)
`googleTokenExpiry`	DateTime?	Token expiration time
`googleConnectedAt`	DateTime?	When Google was connected
`gscSiteUrl`	String?	Search Console property URL
`gscSiteName`	String?	Search Console property name
`ga4PropertyId`	String?	Analytics property ID
`ga4PropertyName`	String?	Analytics property name
`userId`	String	Owner’s user ID (for isolation)
`lastReportGenerated`	DateTime?	Last report timestamp
`totalReportsGenerated`	Int	Count of all reports

Get Started

Core Features

Guides

Plans & Pricing

Connecting Clients

Overview

Prerequisites

Step 1: Add a New Client

Step 2: Connect Google Account

What Happens During OAuth?

Step 3: Select Search Console Property

Step 4: Select Analytics 4 Property

Verification

Managing Multiple Clients

Using Different Google Accounts

Bulk Client Setup

Troubleshooting

”Client not found or unauthorized”

No Search Console Sites Found

Wrong Analytics Property Listed

Token Refresh Failures

“Email verification required”

Client Data Schema

Next Steps

Generate Reports

Customize Branding

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Plans & Pricing

​Overview

​Prerequisites

​Step 1: Add a New Client

​Step 2: Connect Google Account

​What Happens During OAuth?

​Step 3: Select Search Console Property

​Step 4: Select Analytics 4 Property

​Verification

​Managing Multiple Clients

​Using Different Google Accounts

​Bulk Client Setup

​Troubleshooting

​”Client not found or unauthorized”

​No Search Console Sites Found

​Wrong Analytics Property Listed

​Token Refresh Failures

​“Email verification required”

​Client Data Schema

​Next Steps

Generate Reports

Customize Branding

Build docs developers (and LLMs) love

Overview

Prerequisites

Step 1: Add a New Client

Step 2: Connect Google Account

What Happens During OAuth?

Step 3: Select Search Console Property

Step 4: Select Analytics 4 Property

Verification

Managing Multiple Clients

Using Different Google Accounts

Bulk Client Setup

Troubleshooting

”Client not found or unauthorized”

No Search Console Sites Found

Wrong Analytics Property Listed

Token Refresh Failures

“Email verification required”

Client Data Schema

Next Steps