Connect to an OAuth2 API

Most APIs require that you enter some credentials to prove your identity. Usually this will be an API key, which is a unique value similar to a password. With API Connector for Google Sheets, these API keys are easy to use, as they can be simply entered as Header keys or URL query strings. However, many APIs provide access using OAuth 2.0, which is a more secure (and complex) method of authentication and authorization that works through a process of exchanging and refreshing tokens. To enable API access via OAuth 2.0, API Connector includes OAuth 2.0 integrations for several popular API platforms, or lets you add your own custom OAuth2 connection.

This feature is available only for business-plan subscribers, please upgrade to access.

Contents

• Why Use OAuth 2.0?
• How to Connect
• How to Add a Custom OAuth2 Connection
• How to Make an OAuth 2.0 API Request
• Notes

Why Use OAuth 2.0

• some APIs provide access only through OAuth 2.0
• connect by clicking a button rather than digging through documentation for API keys
• avoid needing to manually manage the process of exchanging & refreshing tokens
• connect securely, without needing to enter (and potentially reveal) sensitive access credentials.

How to Connect

1. To access the current list of integrated OAuth 2.0 platforms, click Add-ons > API Connector > Manage Connections, or navigate to the Create screen and click the “Manage connections” link.
   
2. You will see a screen listing the available services.
   
3. Click on the platform you’re interested in connecting to, and you will see a screen on their site prompting you to connect through your account. Every service will look a little different but you may be prompted to accept the connection.
   
4. You’ll now see your new connection reflected in the list. This means you’ve now successfully connected via OAuth 2.0.
   

How to Add a Custom OAuth2 API Connection

If API Connector does not provide a pre-built OAuth2 integration for your platform, you can add your own custom OAuth2 connection.

1. If you haven’t already, enter the Manage Connections screen by clicking Add-ons > API Connector > Manage Connections, or by clicking the “Manage connections” link on the Create screen. Once there, scroll to the bottom and click Add Custom OAuth:
   
2. You will be presented with a screen containing input values for Name, Authorization Base URL, Token URL, Client ID, and Client Secret:
   
3. Choose a name for your custom connection and enter it in the Name field. The other values will be provided by your API platform. Typically you will need to begin by creating an “app”, after which the API will give you a Client ID and Client Secret.
4. During this setup process, your API platform may request that you enter a callback domain or URL. If they require a domain only, enter https://www.google.com. If they require a full callback URL, you should enter this URL: https://script.google.com/macros/d/12COOkin8nodCH7fZGIBu0D2jWY8-AEA0uvElt4Ph4wRbLUD4wslqQUfG/usercallback
5. Every API will work a bit differently, but as an example of what to look out for, if you were connecting to the Google Analytics API, you’d first create an app and register it using the Google API Console. Google then provides the client ID and a client secret, and you’d read their documentation to find the following base and token URLs:
   • Authorization Base URL: https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/analytics.readonly
   • Token URL: https://oauth2.googleapis.com/token
6. After you’ve entered your custom OAuth2 values correctly, click Save. It will then appear on your list of Connections, where you can connect, disconnect, edit, and delete the connection.

How to Make an OAuth 2.0 API Request

Once you have your OAuth 2.0 connection in place, you can select it from the drop-down menu in the Create screen:

The rest of your request will be constructed as usual. Consult your API platform’s documentation for detailed instructions.

Notes

• Some APIs provide multiple methods of connecting, e.g. either an API key or OAuth 2.0. If you’re using the OAuth 2.0 method, just skip their instructions for adding an API key. You don’t need to enter any authentication-related headers if you’re using OAuth 2.0.
• If your OAuth 2.0 connection hasn’t been set up, or you no longer have access, you will receive the following error message: “Request failed: Access not granted or expired.”
• API Connector currently provides pre-built OAuth 2.0 integrations for the AHrefs API, Google Analytics Management API, Google Analytics Reporting API, GitHub API, Harvest API, Instagram Insights API, LinkedIn Ads API, QuickBooks API, Quora Ads API, Vimeo API, and YouTube Analytics API. More integrations are coming soon. Please leave a comment if there are specific APIs you’d like to see.