- đ Quickstart
- đ§âđť OAuth app setup
- đ Useful links
- đ¨ API gotchas
Create an integration
In Nango (free signup), go to Integrations -> Configure New Integration -> Gmail.
Nango has credentials you can use for testing. Activate them in the dashboard.
Authorize Gmail
Go to Connections -> Add Test Connection -> Authorize, then log in to Gmail. Later, youâll let your users do the same directly from your app.
Call the Gmail API
Letâs make your first request to the Gmail API (fetch the profile of the currently signed-in user). This request will return basic details about the authenticated user, such as their email address and message/thread counts. Replace the placeholders below with your secret key, integration ID, and connection ID:Or fetch credentials dynamically via the Node SDK or API.
- cURL
- Node
Copy
curl "https://api.nango.dev/proxy/gmail/v1/users/me/profile" \
-H "Authorization: Bearer <NANGO-SECRET-KEY>" \
-H "Provider-Config-Key: <INTEGRATION-ID>" \
-H "Connection-Id: <CONNECTION-ID>"
Install Nangoâs backend SDK with
npm i @nangohq/node. Then run:Copy
import { Nango } from '@nangohq/node';
const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
const res = await nango.get({
endpoint: '/gmail/v1/users/me/profile',
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>'
});
console.log(res.data);
Next step: Embed the auth flow in your app to let your users connect their Gmail accounts.
You will need to pass a security review to go live with your integration.Follow our guide to get approved as fast as possible.
Create your OAuth App
Create a Google Cloud account
If you donât already have one, sign up for a Google Cloud account.
Create a new project
- Go to the Google Cloud Console.
- Click on the project dropdown at the top left of the page.
- Click New Project.
- Enter a Project Name for your project.
- Under Location, select the appropriate organization or folder where this project should belong.
If youâre not part of an organization, it will default to No organization
- Click Create and wait for the project to be created.
- Select it from the project dropdown.
Enable the APIs you need
- Go to the API Library in the Google Cloud Console.
- Search for Gmail API and select it, then click Enable.
Configure the OAuth consent screen
- Go to APIs & Services > OAuth consent screen in the Google Cloud Console.
- Click Get started.
- Fill in the App Information form.
- App Name: The name of the app asking for consent.
- User support email: For users to contact you with questions about their consent.
- Click Next. Select the appropriate Audience:
- External: For applications available to any Google user
- Internal: For applications restricted to users within your Google Workspace organization
- Click Next. Fill in the Contact Information; these are the email addresses that Google will use to notify you about any changes to your project.
- Click Next, then check the I agree to the Google API Services: User Data Policy checkbox, and click Continue.
- Add the scopes your application needs. Under Data Access, click Add or Remove Scopes and select the scopes that correspond to the APIs you enabled.
- Under Audience, click Add users if you selected External user type (required for testing before verification).
Create OAuth 2.0 credentials
- Go to APIs & Services > Credentials in the Google Cloud Console.
- Click Create Credentials and select OAuth client ID.
- Select Web application as the application type.
- Enter a name for your OAuth client.
- Under Authorized redirect URIs, add
https://api.nango.dev/oauth/callback. - Click Create.
- A dialog will appear with your client ID and client secret. Save these credentials securely as youâll need them when configuring your integration in Nango.
Start building your integration
Follow the Quickstart to build your integration.
Verify your app
Most Gmail scopes are marked âsensitiveâ or ârestrictedâ by Google. You need to pass a Google review to go live.You can develop your integration in test mode, but you need to pass a security review to go live.Follow our guide to prepare and pass as quickly as possible.
Common Scopes
| Scope | Description |
|---|---|
profile | Access to userâs basic profile information |
email | Access to userâs email address |
https://mail.google.com/ | Read, compose, send, and permanently delete all emails from Gmail |
https://www.googleapis.com/auth/gmail.readonly | View email messages and settings |
https://www.googleapis.com/auth/gmail.send | Send email on the userâs behalf |
https://www.googleapis.com/auth/gmail.compose | Manage drafts and send emails |
API gotchas
- From the scopes page, make sure to select scopes based on the APIs you enabled earlier when setting up the app.
- Under certain circumstances, Google expires a userâs refresh token and the token refresh in Nango will fail. You can find a list of reasons from Google here, including:
- The user has revoked your appâs access.
- The user changed passwords and the refresh token contains Gmail scopes.
- The user account has exceeded a maximum number of granted (live) refresh tokens.
- The user granted time-based access to your app and the access expired.
- If an admin set any of the services requested in your appâs scopes to Restricted.
- For Google Cloud Platform APIs - the session length set by the admin could have been exceeded.
- In âTestingâ mode with an external user type, refresh tokens expire in 7 days unless only basic scopes are used â userinfo.email, userinfo.profile, openid, or their OpenID Connect equivalents. You can remove this 7-day limit by switch from Testing to Production. Follow step 6 in the Setup Guide above.
- Google allows up to 100 refresh tokens per account per OAuth client ID; new tokens overwrite the oldest without warning when the limit is reached.
- While setting up the OAuth credentials, the Authorized JavaScript origins should be your site URL (
https://app.nango.devif youâre testing from the Nango UI). - For applications using sensitive or restricted scopes, Google requires verification and a security assessment. This process can take several weeks to complete.
- Googleâs OAuth consent screen has different configurations for âExternalâ and âInternalâ user types. Internal is only available for Google Workspace users and limits access to users within your organization.
- Google implements incremental authorization, allowing you to request additional scopes over time without requiring users to re-authorize all previously granted scopes.
- Google enforces rate limits on API requests, which vary depending on the specific API being used.
Contribute API gotchas by editing this page
Questions? Join us in the Slack community.