Settings

System Settings

Setup required

Google Workspace

Setup required

Google OAuth is not configured on this server

The integration is fully implemented — connecting an account needs credentials that only an administrator can create, and a server restart to pick them up. Each step below is one-time. Secrets belong in .env.local, which is gitignored; never commit them.

  1. 1

    A Google Cloud project with the Gmail and Calendar APIs enabled

    In console.cloud.google.com, create (or pick) a project, then enable both the Gmail API and the Google Calendar API under APIs & Services → Library.

  2. 2

    OAuth consent screen configured

    Google Auth Platform → Audience and → Data access (formerly "APIs & Services → OAuth consent screen"). "Internal" is enough for a Workspace domain. An External app must stay in Testing with each Google account added under Test users — note that Testing authorizations expire 7 days after consent, taking the refresh token with them, so Internal is strongly preferred for a daily-use tool. Add the six read-only scopes listed below. gmail.metadata is a RESTRICTED scope (not merely sensitive): an External app in Production would need Google verification plus a recurring third-party CASA security assessment. Testing mode avoids both.

  3. 3

    An OAuth 2.0 Client ID of type "Web application"

    Google Auth Platform → Clients → Create client (formerly "APIs & Services → Credentials"). Add exactly this Authorized redirect URI — Google matches it byte-for-byte, including scheme, case and trailing slash: https://crm.gopaxx.de/api/integrations/google/callback

  4. 4

    Client ID available to the serverGOOGLE_OAUTH_CLIENT_ID

    Set GOOGLE_OAUTH_CLIENT_ID in the server environment (.env.local — never committed).

  5. 5

    Client secret available to the serverGOOGLE_OAUTH_CLIENT_SECRET

    Set GOOGLE_OAUTH_CLIENT_SECRET in the server environment. It is read server-side only and is never sent to the browser.

  6. ✓

    Token encryption keyPAXX_TOKEN_ENCRYPTION_KEY

    Set PAXX_TOKEN_ENCRYPTION_KEY to a 32-byte key (openssl rand -base64 32). Refresh tokens are encrypted with AES-256-GCM before they reach the database; without this key PAXX refuses to store them rather than storing them in plaintext.

  7. ✓

    Public base URL (only if PAXX is not on http://localhost:3000)PAXX_PUBLIC_URL

    Set PAXX_PUBLIC_URL (e.g. https://command.gopaxx.de) so the redirect URI PAXX generates matches the one registered with Google. Alternatively set GOOGLE_OAUTH_REDIRECT_URI directly.

Authorized redirect URI — must match exactly

https://crm.gopaxx.de/api/integrations/google/callback

Still missing: GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET

Permissions PAXX will request — all read-only

  • Sign-in identityread

    Identifies which Google account granted access, so the two account slots can be told apart.

  • Email addressread

    Labels the connected account in Settings and tags every mail/calendar item with its source account.

  • Name and profile pictureread

    Shows a recognisable account identity instead of a bare email address.

  • Gmail headers and labels — no message bodiesread

    Reads sender, subject, timestamp, labels and thread structure. Google will not return message bodies or attachments under this scope.

  • List of your calendarsread

    Lets PAXX show which calendar an event came from when several are connected.

  • Calendar eventsread

    Reads today's schedule, upcoming events, attendees and meeting links.

Until OAuth is configured, Gmail and Calendar panels across the Command Center are served by the mock connectors and carry a MOCK provenance badge. No Google account is contacted and no credential exists.

Primary Google account

No account connected to this slot. Two Google accounts are supported — connect them one at a time; Google's account chooser is shown each time, so the second connection can use a different account.

Picking an account that already occupies the other slot moves it here and leaves that slot empty — one Google identity can only be connected once.

Connect — unavailable until setup is complete

Second Google account

No account connected to this slot. Two Google accounts are supported — connect them one at a time; Google's account chooser is shown each time, so the second connection can use a different account.

Picking an account that already occupies the other slot moves it here and leaves that slot empty — one Google identity can only be connected once.

Connect — unavailable until setup is complete
Open MailOpen Calendar

Security boundary

What PAXX can and cannot do with these accounts

GREEN Read mail metadata and calendar events. Active. Headers, labels, thread structure, events, attendees. No message bodies — the gmail.metadata scope does not return them.

YELLOW Connect, reconnect, disconnect, toggle a capability. Requires the integrations:configure capability (admin or owner) and is recorded in the audit log with the scopes granted. Google's own consent screen is a mandatory human approval step inside the flow, which is why this is YELLOW rather than RED despite storing a credential.

RED Send email, create a draft in Gmail, or modify a calendar. Not implemented and not reachable: no send/compose/modify scope is requested (a unit test fails if one is added to the scope table), and the send helper throws unconditionally. Enabling it would be a deliberate, reviewable change requiring per-message human approval.

Refresh tokens are encrypted with AES-256-GCM before they reach the database and live in a separate table from the account record, so listing accounts never reads ciphertext. No token is ever sent to the browser. Disconnecting revokes the grant at Google first, then deletes the local credential.