Search API Connector Documentation
Create a Custom OAuth2 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. For example:
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
- First, 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 past the preset connections 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: Typically you will need to login to the developer section of your platform and create an app, after which the API will give you your Client ID and Client Secret.
- During this app setup process, your API platform may request that you enter a redirect or callback URL. This is the URL:
- 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 (for an in-depth walkthrough, see this article).
- 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:
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.
- 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 make sure you’re connected.