Creating an OAuth App for Gmail

Introduction

Gmail is Google's email service that allows users to send and receive emails, organize messages with labels and filters, and integrate with other Google services. Integrating Gmail into your application enables users to read, send, and manage their email directly from your app via the Proxy API. This guide walks you through the steps to create an OAuth app for Gmail integration.

Our sandbox application didn't go through the full Google security audit. If the app or site doesn't meet Google's security standards, Google might block you from signing into your account via it by default. This can be turned off if you understand the risk: https://myaccount.google.com/lesssecureapps. This guide describes how to create your own sandbox application.

Step 1: Prerequisites

Before you begin, make sure you have the following:

1. A Google account
2. An Apideck account

Step 2: Setting up the Google Developer Console

1. Navigate to the Google Developer Console.
2. Sign in with your Google account.
3. If you haven't created a project yet, click the "Create Project" button and follow the prompts. Otherwise, select an existing project.

Step 3: Enabling the Gmail API

1. In the Google Developer Console, click on the "Enable APIs and Services" button.
2. Search for "Gmail API" in the search bar and click on it.
3. Click the "Enable" button to enable the Gmail API for your project.

Step 4: Creating OAuth 2.0 credentials

1. Navigate to the "Credentials" tab on the left side of the Google Developer Console.
2. Click on the "Create credentials" button and select "OAuth client ID" from the dropdown menu.
3. Choose the appropriate application type, depending on your project (e.g., Web application, Android, iOS, etc.).
4. Fill in the required fields:
   • Name: A descriptive name for your OAuth client
   • Authorized JavaScript origins: Your application's domain (if applicable)
   • Authorized redirect URIs: https://unify.apideck.com/vault/callback
5. Click "Create" to generate your OAuth client ID and secret.

Copy these credentials to configure in Apideck:

Step 5: Configuring your OAuth consent screen

1. Navigate to the "OAuth consent screen" tab on the left side of the Google Developer Console.
2. Choose "External" or "Internal" user type, depending on your app's target audience.
3. Fill in the required fields:
   • App name: Your application name
   • User support email: Your support email address
   • App logo: Your application logo (optional)
   • Developer contact information: Your developer email
4. Under "Scopes," click the "Add or Remove Scopes" button and add the appropriate Gmail scopes based on your needs:

Available Gmail Scopes

Recommended scopes for full Gmail functionality:

• https://www.googleapis.com/auth/gmail.modify - For read/write access without permanent deletion
• https://www.googleapis.com/auth/gmail.send - For sending emails

5. Save your changes and submit your consent screen for verification if required.

Google App Verification Process Details

If your app will be used by more than 100 users or requests sensitive scopes (which Gmail access is considered), you need to complete Google's verification process:

1. Complete your OAuth consent screen: Ensure all required fields are filled in (app name, support email, developer contact information, privacy policy URL, etc.)

2. Add appropriate scopes: For Gmail, add the scopes your application needs

3. Submit for verification: Click "Submit for verification" button on the OAuth consent screen page

4. Verification requirements:

   • Valid privacy policy URL that properly describes data collection and usage
   • A homepage or landing page for your application
   • Demonstration of legitimate use case for requested scopes
   • Screenshots or video of your application's OAuth implementation flow

5. Verification timeline:

   • Basic verification typically takes 3-5 business days
   • Apps requesting sensitive scopes (like Gmail) may require 4-6 weeks for review

6. During review period:

   • You can test with up to 100 users (Developer Identity) even without verification
   • For internal company use, consider using "Internal" user type which doesn't require verification

Important: While waiting for verification, you can still use your application in development/testing mode with up to 100 users, or by having users click "Advanced" and then "Continue to [your app]" when they see the unverified app warning.

Step 6: Configure a Custom redirect URI

To enable the connection to your Gmail instance and be compliant with the Google certification, it is required to use your own white label auth URIs.

Redirect URI: https://unify.apideck.com/vault/callback

Setup a custom subdomain for Apideck Vault (Optional)

Add a custom domain name for Apideck Vault. This will allow you to white label the reference to Apideck's Vault.

1. Create a CNAME record

Sign in to your DNS name server host and navigate to your DNS settings. Add a CNAME record with the value cname.vercel-dns.com.

[REPLACE_WITH_DESIRED_SUBDOMAIN] CNAME cname.vercel-dns.com.

2. Contact Apideck

Get in touch with your Apideck contact or support@apideck.com to let us know about the custom domain you want to use, so we can configure & enable it for Apideck Vault.

3. Wait for the changes to propagate

When DNS changes are made, you can expect a propagation time up to 24 hours (but mostly much less than that).

4. Update the "Redirect URI"

Update the "Redirect URI" in your Google Cloud Console credentials to match your custom domain.

Step 7: Configure in Apideck

1. Navigate to the Apideck Gmail connector settings
2. Under Use your Gmail client credentials, enter:
   • Client ID: The OAuth client ID from Google
   • Client Secret: The OAuth client secret from Google
3. Configure the scopes you want to request from users
4. Save your configuration

Test with the Proxy API

1. Connect through Vault
2. Use the Proxy API to access Gmail endpoints directly while Apideck handles authentication:

curl --location 'https://unify.apideck.com/proxy' \
  --header 'x-apideck-consumer-id: test-consumer' \
  --header 'x-apideck-app-id: {APIDECK_APP_ID}' \
  --header 'x-apideck-service-id: gmail' \
  --header 'x-apideck-downstream-url: https://gmail.googleapis.com/gmail/v1/users/me/messages' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}'

FAQ and troubleshooting

Error: access_denied

Cause: The user declined to grant access, or the OAuth consent screen is not properly configured.

Solution:

1. Verify your OAuth consent screen is complete
2. Ensure all required scopes are added to your app
3. Check that the redirect URI matches exactly

Error: invalid_scope

Cause: Requesting a scope that isn't enabled for your OAuth app.

Solution: Add the missing scope to your OAuth consent screen configuration in the Google Developer Console.

Error: unauthorized_client

Cause: The OAuth client ID is not authorized for the requested operation.

Solution:

1. Verify the Client ID and Secret are correctly entered in Apideck
2. Ensure the redirect URI https://unify.apideck.com/vault/callback is added to Authorized redirect URIs

Users see "This app isn't verified" warning

Cause: Your app hasn't completed Google's verification process.

Solution:

• For testing: Users can click "Advanced" > "Continue to [app name]"
• For production: Complete the Google verification process as described in Step 5

Conclusion

By following this guide, you have successfully created an OAuth app for Gmail integration. Your users can now connect their Gmail accounts through Apideck Vault and access Gmail via the Proxy API.

For more information on Gmail API capabilities, refer to Google's Gmail API documentation.