Search API Connector Documentation
Create a Custom OAuth Connection
If API Connector does not provide a preset OAuth2 integration for your platform, you can add your own custom OAuth2 connection.
- Before You Begin
- What is OAuth 2.0?
- Why Create a Custom OAuth Connection?
- How to Add a Custom OAuth Connection
- Custom OAuth Example
- How to Activate the Connection
Before You Begin
Click here to install the API Connector add-on from the Google Marketplace.
What is OAuth 2.0?
Most APIs require some kind of authorization. Frequently this involves entering an API key or token, which function similarly to passwords.
OAuth2 is an alternative authorization framework that lets a user securely connect a third party to their account without manually entering or exposing their credentials.
You've probably encountered OAuth2 before. It's the technology behind most "sign in with X" authorization flows.
Why Create a Custom OAuth Connection?
- some APIs provide access only through OAuth 2.0, and do not enable API keys/tokens.
- access APIs or scopes not available in our preset OAuth connections.
- keep your connection totally secure. Only authorized users can connect to your custom OAuth2 connection.
How to Add a Custom OAuth Connection
Step 1: Configure an App
- To get started, you generally need to enter the developer section of your API platform and configure an "app". Some APIs may ask you to simply click a few buttons, while others will ask that you provide detailed information or a video walkthrough of the data you intend to access.
- During this process, the API platform usually requests that you enter a redirect or callback URL. This is the redirect URL for API Connector:
- Once you've finished setting up your app, the API should provide you with a Client ID and Client Secret.
Step 2: Configure API Connector
After retrieving the Client ID and Secret, you can move on to setting up the connection in Google Sheets.
- Enter the Manage Connections screen by clicking Extensions > 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:
- You will be presented with a screen containing input values for Name, Authorization Base URL, Token URL, Client ID, and Client Secret:
- Fill out these values as follows:
- Name: Choose a name for your custom connection and enter it in, e.g. "Custom BigQuery".
- Authorization Base URL: This should be provided within the API's developer documentation, and usually contains the word "auth" or "oauth" somewhere in the URL. Some APIs require that you include a parameter for the scope(s) you wish to access, and that would get included on the end of this auth URL. The OAuth2 connection manager will automatically handle all the standard OAuth2 parameters: client ID, client secret, code, grant_type, redirect_uri, response type, and state. Therefore you generally don't need to add any parameters besides scope.
- Token URL: This will also be provided within the API's developer documentation, and usually contains the word "token".
- Client ID and Client Secret: These will be provided by the API as described above.
- After you've entered your custom OAuth2 values, click Save. The custom connection will then appear on your list of Connections, where you can connect, disconnect, edit, and delete the connection.
Custom OAuth Example
Every API will work a bit differently, but let's look at the Google BigQuery API as an example of what to look out for.
- Go to the Google API Console and register an app
- When you finish registering the app, Google provides a client ID and a client secret.
- Read the API documentation to find the authorization and token URLs. For Google BigQuery it would be these:
- Authorization Base URL:
- Token URL:
- Authorization Base URL:
This site also has many articles containing complete examples of setting up custom OAuth connections:
- Import Basecamp Data to Google Sheets
- Import Dr Chrono Data to Google Sheets
- Import Help Scout Data to Google Sheets
- Import RD Station Data to Google Sheets
- Import Salesforce Data into Google Sheets
- Import Snapchat Ad Data to Google Sheets
- Import Twitch Data to Google Sheets
- Import Yahoo Fantasy Sports Data to Google Sheets
- Import Zoho Data to Google Sheets (Any Application)
How to Activate the Connection
- First, click Connect to authenticate yourself through your new connection.
- Assuming everything was set up correctly, you'll be taken to the target site and prompted to connect your account.
- Once you accept, you’ll see your new connection reflected in both the Connections list and under the OAuth dropdown menu.
- Now you can enter your request details and choose your custom connector to run your request.
- Custom OAuth2 connections are only saved to the sheet in which they're created. Unlike preset connections, they won't be available in other sheets.
- The custom OAuth2 connection manager currently only supports the Authorization Code grant type, which is the most common OAuth2 flow. If your API uses another flow like the Client Credentials grant type, get your token by sending a
"grant_type":"client_credentials"request body in a standard API request (this comment gives a bit more detail).
- 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." In that case, go back to the Connections screen and click Connect again.