Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 8.57 KB

How do I set up custom Google OAuth credentials for Google Docs?

Use your own Google OAuth app when you want your app's name on Google's consent screen, a dedicated API quota, or scopes that Composio's managed app doesn't cover.

Create the Google OAuth app

  1. Open the Google Cloud console and select the project that will own the OAuth app, or create one.

Google Cloud project picker with the OAuth app's project selected

  1. Go to APIs & Services → Library, search for Google Docs API, and click Enable. The default scopes include Drive access, so enable the Google Drive API too if your tools search or manage documents through Drive. If the API page shows Manage, the API is already enabled. Enabling an API needs project permissions; ask your project admin if you can't.

Google Docs API page in the Google Cloud API Library with the Enable button

  1. Go to Google Auth Platform → Branding. If you see Get started, enter the app name, user support email, and developer contact email, then save.

Google Auth Platform Branding page with the app name and user support email fields

  1. Under Audience, choose the user type. Internal limits sign-in to accounts in your Google Workspace organization. External allows any Google account. An External app starts in Testing; add every account that will connect under Test users.

Google Auth Platform Audience page showing Testing status, the External user type, and Test users

  1. Under Data Access, click Add or remove scopes and add the scopes your auth config will request (see Scopes below). Paste any scope missing from the list under Manually add scopes and click Add to table. Click Update, then Save.

Data Access scope picker with the documents.readonly scope selected

  1. Under Clients, click Create client. Set Application type to Web application, name the client, and add this URI under Authorized redirect URIs:
   https://backend.composio.dev/api/v1/auth-apps/add

It must exactly match the oauth_redirect_uri field of your Composio auth config.

Create OAuth client ID form with Web application selected

Create OAuth client ID form with the Composio redirect URI under Authorized redirect URIs

  1. Click Create. Copy the Client ID and Client secret before you close the dialog, and store the secret privately.

OAuth client created dialog with the Client ID and Client secret

Create the auth config in Composio

  1. In the Composio dashboard, go to Auth Configs → Create and select Google Docs. Enter a config name and click Next.

Composio Auth Configs page with the Create button

Create Auth Config dialog with Google Docs in the toolkit search results

Config Name field for the new Google Docs auth config

  1. Choose OAuth 2.0 and Your Own Credentials. Paste the Client ID and Client secret, and leave Redirect URI set to https://backend.composio.dev/api/v1/auth-apps/add.

Google Docs auth config form with Client ID, Client secret, the Composio redirect URI, and a selected scope

  1. Choose the scopes your tools need, matching the ones you added under Data Access, then click Create Auth Config.
  2. Click Connect Account, sign in with a Google account that can use the app (a test user while the app is in Testing), and approve the consent screen. Under Accounts, confirm the connection shows Active.

Google's unverified-app notice for an app in Testing

Google consent screen asking to see all Google Docs documents

Google Docs auth config details with an Active connected account

For the general flow, see custom auth configs.

Scopes

The default Google Docs auth config requests https://www.googleapis.com/auth/documents, https://www.googleapis.com/auth/drive, and userinfo.email. To only read documents by ID, documents.readonly is enough. Editing needs documents, and finding documents through Drive needs a Drive scope. See Google's Docs scope reference.

Short scope names on this page leave out the https://www.googleapis.com/auth/ prefix. When you paste a scope under Manually add scopes, use the full URL, for example https://www.googleapis.com/auth/userinfo.email. Scopes already written as a full URL, such as https://mail.google.com/, go in as shown.

If you change the scopes later, reconnect the account so the user grants the new access.

Testing, publishing, and verification

  • While an External app is in Testing, only test users can connect, and Google can show them an unverified-app notice. Google generally expires their authorizations after seven days, so they need to reconnect.
  • To let any Google account connect, publish the app under Audience. Publishing doesn't verify the app.
  • Public apps that request sensitive or restricted scopes generally need Google's OAuth verification. Check Google Auth Platform → Verification Center. Internal apps and apps in Testing can be exempt. See Google's verification requirements.
  • The default drive scope is restricted. A public app that requests it needs restricted-scope verification, which can include a security assessment.
  • If Google blocks sign-in, check the app's audience, the test user list, the requested scopes, and your Workspace admin's app access policy.

Why am I seeing "App is blocked" when connecting Google Docs?

The OAuth client is requesting scopes that Google hasn't verified for that client. This usually happens when you add extra scopes beyond the defaults.

Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification, as described in the setup steps above.

Why am I getting "Google Docs API has not been used in project" error?

When using custom OAuth credentials, the Google Docs API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.

Why am I getting "Error 400: invalid_scope"?

The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the Google OAuth scopes docs. If you're creating auth configs programmatically, see the programmatic auth config guide.

By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See White-labeling authentication.

Why am I getting 401 errors on tool calls?

The user's access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google's refresh token limit was exceeded. Re-authenticating the user typically resolves this.

Why am I getting "Quota Exhausted" or "rate limit exhausted"?

Google enforces per-minute and daily request quotas. If you're using Composio's default OAuth app, you share that quota with other users, which can cause limits to be hit faster. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits.