Skip to main content
On a self-hosted install you register one Google OAuth app as the server admin. Each member then connects their own Gmail and Google Calendar from Integrations. No Composio account is needed. OpenNous Cloud connects Google for you, so none of this applies there.

​
Server setup

1

Create a Google Cloud project

Go to console.cloud.google.com and create a project, or pick an existing one.
2

Enable the Gmail API and the Google Calendar API

In APIs & Services → Library, search for each one and click Enable:
  • Gmail API
  • Google Calendar API
Screenshot 2026 05 18 At 11 07 39 AM
3

Configure the OAuth consent screen

Go to APIs & Services → OAuth consent screen (in newer consoles: Google Auth Platform → Branding / Audience / Data access).
  • User type. Choose Internal if everyone who will connect is in your own Google Workspace organization. Internal apps need no Google verification. Otherwise choose External.
  • App information. Enter an app name, a support email and a developer contact email.
  • Scopes. Add exactly these. OpenNous asks for nothing else:
gmail.readonly is a restricted scope. With an External app in Testing status, only the test users you add can connect, and Google expires their refresh tokens after 7 days, so they have to reconnect every week. For lasting connections, use an Internal app or publish the External app and complete Google’s verification.
4

Create the OAuth client

Go to APIs & Services → Credentials → Create credentials → OAuth client ID.
  • Application type: Web application
  • Authorized redirect URIs: add your API domain followed by the callback path, exactly as written:
Screenshot 2026 05 18 At 11 10 20 AM
For example, https://api.yourdomain.com/api/oauth/google/callback. You don’t need Authorized JavaScript origins.
Screenshot 2026 05 18 At 11 11 57 AM
5

Copy the Client ID and Client secret

Google shows both once the client is created. You can also find them later under Credentials.
6

Add them to nous.env and restart

GOOGLE_OAUTH_REDIRECT_URI is optional. Leave it out and OpenNous uses https://<API_DOMAIN>/api/oauth/google/callback. If you set it, it must match the redirect URI on the OAuth client exactly. Restart so the API and the worker read the new values:
Tokens are stored encrypted with ENCRYPTION_KEY, so that must be set as well. It already is on a standard install.
Composio is optional. If you set COMPOSIO_API_KEY, or a workspace admin pastes a Composio key in the app, that workspace connects Google through Composio instead. When all three GOOGLE_* variables are set and no Composio key is present, OpenNous uses your Google app.

​
Connecting in OpenNous

Every member connects their own account. Gmail and Calendar are two separate connections:
  1. Open Integrations (Personal).
  2. Click Add, choose Gmail or Google Calendar, then click Connect with Google.
  3. Sign in and approve the read-only access in the popup. Leave the Gmail or Calendar permission ticked: a connection without it is refused.
The popup finishes in the tab that opened it, under your own login. A consent link forwarded to someone else connects nothing; if the popup can’t reach the OpenNous tab that opened it, it cancels the sign-in.
Sign-ins in progress are held in the API process for up to 10 minutes. The bundled stack runs one API container, which is what this expects. If you run several API instances behind a load balancer, use sticky sessions.
Connecting a second Google account adds a second row. Connecting the same account again updates the existing row. Disconnecting removes the row. The grant at Google is revoked only when no other connection on this server uses the same Google account (Google keeps one grant per account), so disconnecting Gmail while Google Calendar stays connected keeps it. A Google account already connected by another member of the workspace can’t be connected again by someone else.

​
What gets synced

Email is filed only against people who are already in OpenNous. It never creates contacts. Each email is one record, and its content is visible only to its participants and to the members whose mailboxes hold it. For calendar rules, see Google Calendar.

​
Troubleshooting