You must create and add your own Google APIs Project and OAuth credential to your CloudSponge account before you can access Gmail address books. This is because Google has asked us to ensure that any app that is consuming their data has a registered developer account with Google. This has the added benefit of providing a better experience for your users, who will see your product consistently through the OAuth flow.
Important: Google needs to verify your application before they will allow strangers to approve your OAuth permission requests. Google warns that the verification may take up to a week. However, in our experience the verification may be as fast as one business day if you meet Google’s approval criteria. We’ve prepared some background and directions to help you navigate the new process successfully. You can still develop and test your integration before Google has verified it.
These are the actions required to set up your Google OAuth:
- If you haven’t already done so, create a Proxy URL on your application’s domain.
- Create a Google APIs Project and OAuth 2.0 Credentials.
- Configure your CloudSponge account with your Google OAuth credentials.
- Request verification from Google, if your APIs Project is for HTTPS.
Create a Google APIs Project and Get your OAuth 2.0 Credentials
There are two types of Google APIs Project that you can create, an APIs Project for HTTPS or an APIs Project for non-HTTPS.
Before you can access Gmail Address Books in your live site, you’ll need to create a Google APIs Project for HTTPS. CloudSponge customers typically create a single APIs Project for HTTPS because it usually can be used with CloudSponge in all of your environments.
You will need to configure OAuth for at least one Google APIs Project, depending on how your production, staging and development environments are hosted. Each Google APIs Project can be used on registered domains (and sub-domains) hosted on either HTTPS or non-HTTPS. The one useful exception to this rule is for
http://127.0.0.1[:port]. These URLs are always valid for any Google APIs project.
Creating an APIs Project for HTTPS
You’ll need to create an APIs Project for HTTPS for your live/production environment. As the name implies, your server must be hosted on HTTPS. Before your set up is complete, you’ll need to create an HTTPS Google APIs Project and have it verified by Google.
An HTTPS project can be verified by Google so that your users don’t see the egregious warning screen when asked to share their address books with your application. This project can be used on any sub-domains that also use HTTPS, as well as for localhost development. Your production site must use an HTTPS Google APIs Project.
You need a Proxy URL to be hosted on your HTTPS server on the same domain or sub-domain as your production site. For example, if your root application domain is
example.com, your Proxy URL could be hosted at
Setting up Google OAuth for an HTTPS environment
Armed with your Proxy URL hosted in a public HTTPS environment, you are able to complete the set up of the Google APIs Project.
- Sign in to the Google APIs Platform.
- Create a new project and enable the necessary APIs:
- Create a new project, possibly from the Manage resources page.
- You should land on the new project’s home screen which has a link to Enable APIs and … in the Getting Started section. Go ahead and click that link.
- From your Project’s dashboard, click Enable APIs and then search for
contacts. Here’s a handy pre-populated link.
- Enable the Contacts API from here.
- Also, enable the People API from here. This is a new requirement for setting up your Google APIs Project for HTTPS.
- Configure the OAuth consent screen settings:
- Visit the OAuth consent screen settings for your new project.
- Enter your Application name. Your users will see this name when asked for permission to access their address book.
- Upload an Application Logo. This step is optional but recommended. A logo gives users a visual cue that they can trust the application asking for permission so it’s very important for live apps.
- Pick a Support email from the list. Users will see this email if they look for it on the OAuth permission page.
- Click Add scope, select the
../auth/contacts.readonlyscope and click ADD. This step is critically important if you are going to use the credentials in production.
- Add your apex domain to Authorized domains. If you have multiple domains for the same product, add them here. Any sub-domains of the application domains can be used for your project’s Privacy URL or Proxy URL. If you change this value after your application has been verified by Google, you’ll need to get them to verify your project again.
- Fill in the Application Homepage link. This URL must be publicly available and hosted on one of your Authorized domains.
- Optionally, fill in the Application Terms of Service link. This step is recommended if you have a ToS for your users. This URL must be hosted on one of your Authorized domains.
- Click Save (You’ll Submit for verification later, after creating the OAuth credentials).
- Create credentials:
- Visit the credentials tab and click Create credentials > OAuth client ID. Or go straight to the new OAuth client page.
- Under Application type, select Web application.
- Name your credential however you like; users don’t see this label.
- In Authorized redirect URIs, enter your Proxy URL. Click outside the input field so that the form validates the URL.
- Click Create.
- Make a note of your Client ID and Client Secret. You will add these values to your CloudSponge account.
- Click over your app credentials in order to view details.
- Take note of your
- Click over your app credentials in order to view details.
Configure your CloudSponge account with your Google OAuth credentials
- Sign in to your CloudSponge account and visit your credentials page.
- Click the Add OAuth Credential button.
- Select “Gmail” and click Next.
- Select your Proxy URL from the list or click “Add new Proxy URL” to add and verify a new one. Click Next.
- Enter a
Nameto help identify this credential, the
Client secretvalues from Google. Select Default Gmail Client checkbox if this credential will be used in your production and development environments. If you don’t select the Default checkbox, you’ll also need to assign this credential to the sites that should use it. in step
- When you are satisfied with the values, click on Save & Close button.
Optionally, you may assign the newly created credential to one or more sites explicitly. When you assign a credential with a site, this overrides the “Default” setting for your account. Usually, this is not required, since you can use your production credential in your development environments. However, if you support multiple sites with different OAuth credentials, then you’ll need to make the assignments as follows.
- Open your sites page.
- Click the Assign OAuth button for the site to which you’d like to assign a credential.
- Select the credential by name from the list of credentials for your account.
- You are done. Go ahead and test an address book import to confirm that the correct credential is used on your site.
NB If you observe a 400 error with a message of “Error: invalid_scope” when you attempt to complete the OAuth flow, then your OAuth account needs to be reviewed before Google will let you request access to people’s address books. This is a new requirement that they introduced on May 11, 2017. We’ve prepared some background and directions for navigating the new review process.
Request a Verification from Google
Only projects that are on HTTPS can be verified by Google. Projects that are not verified by Google display a strong warning to the user and can only be used by 100 users before being disabled. You must host your live application on HTTPS and successfully pass Google’s verification.
Before you request a verification from Google, you should:
- Verify your domain with Google.
- Read about App verification
- Finally, review Google’s list to ensure approval.
Read our background and directions for a quick turnaround from the review process.
When you are ready to request a review, visit your Project’s consent settings and click the Submit for verification button. Fill in the form, explaining how you are using the Contacts API.
If you have any questions, reach out to us. We’re happy to help however we can.