- đ Quickstart
- đ§âđť OAuth app setup
- đ Useful links
- đ¨ API gotchas
1
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.
2
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.
3
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
Ask AI
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
Ask AI
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
1
Create a Google Cloud account
If you donât already have one, sign up for a Google Cloud account.
2
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.
3
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.
4
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).
5
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.
6
Start building your integration
Follow the Quickstart to build your integration.
7
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.
8
Publish your app (switch from Testing to Production)
To move your OAuth app from testing to production:
- Go to APIs & Services > OAuth consent screen > Audience.
- Click Publish App to switch your app from testing to production.
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.