Search API Connector Documentation

Print

Create a Custom OAuth2 Connection

premium

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

Contents

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:

oauth2-img0

That’s OAuth2!

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

  1. First, enter the Manage Connections screen by clicking Add-ons > API Connector > Manage Connections, or by clicking the “Manage connections” link on the Create screen.
    custom-oauth2-img1
  2. Once there, scroll past the preset connections and click Add Custom OAuth:
    oauth2-img7
  3. You will be presented with a screen containing input values for Name, Authorization Base URL, Token URL, Client ID, and Client Secret:
    oauth2-img8
  4. 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.
  5. During this app setup process, your API platform may request that you enter a redirect or callback URL. This is the URL: https://script.google.com/macros/d/12COOkin8nodCH7fZGIBu0D2jWY8-AEA0uvElt4Ph4wRbLUD4wslqQUfG/usercallback
  6. 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.
    bigquery-img13
  • Read the API documentation to find the authorization and token URLs. For Google BigQuery it would be these:
    • Authorization Base URL: https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/bigquery/insights
    • Token URL: https://oauth2.googleapis.com/token

How to Activate the Connection

  1. First, click Connect to authenticate yourself through your new connection.
    custom-oauth2-img3
  2. Assuming everything was set up correctly, you’ll be taken to the target site and prompted to connect your account.
    custom-oauth2-img4
  3. Once you accept, you’ll see your new connection reflected in both the Connections list and under the OAuth dropdown menu.
    custom-oauth2-img5
  4. Now you can enter your request details and choose your custom connector to run your request.
    custom-oauth2-img6

Notes

  • 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.

Tags:
Previous Basic Authentication
Next Filter Fields (JMESPath)

18 thoughts on “Create a Custom OAuth2 Connection”

    • Sure, API Connector works with any kind of token. They provide a cURL expression to get your token: curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD" -X POST https://api.virtuoussoftware.com/Token
      So I think the easiest is to just substitute in your email and password, and then just copy and paste the whole expression into the cURL importer (Add-ons > API Connector > Import/Export > Import cURL). This will parse the expression and automatically configure it for API Connector so you can just hit Run to get your token.
      Then, follow the docs and use your token in the header like this: Key = Authorization, Value = Bearer . You can reference that token in its cell so you don’t need to keep typing it in whenever the token updates. Hope that clarifies.

      Reply
  1. Hi –

    Is there a way to set the access and refresh token? The OAuth2 service I want to connect to doesn’t use the normal OAuth2 “connect” workflow for some reason. They just give the client id, secret, access, refresh token, and token url.

    Thanks!

    Reply
    • Sure, it’s totally fine to manually handle OAuth2 (or the various requests within the flow). In that case, instead of using API Connector’s built-in OAuth2 connection manager, you’d set up a series of “regular” API requests and go through the OAuth2 flow manually.

      Reply
  2. Hi. Is it possible to create a simple connector for google sheets with the Scope user.email ?

    I have a sheet with multiple editors added and i will welcome the editor with his google-email.
    cell A1 is “Welcome” and cell A2 is “=ACTIVEUSER()”.
    This function calls activeUser = Session.getActiveUser().getEmail();
    But there is a authorisation required and i have problems to handle this.

    Thank you 🙂

    Reply
    • Hey Sven, sorry, I don’t know any way to pass in a dynamic value for the scope. Generally you don’t need to pass in the value for the ’email’ scope yourself anyway, it’s just used to make the platform pop up a login modal so the user can log in with their own email address. So users click Connect, then they see the popup and authorize the connection with their own account. That means multiple users can connect through a single OAuth2 connection, but they each need to authorize themselves individually.Hope that helps clarify, if not, let me know and I’ll try to explain further.

      Reply
  3. Hello, firstly I greatly appreciate all your work on this tool, it is simply incredible.

    I am trying to get Coinbase OAUTH2 to work. I want OAUTH2 because I intend to have someone else use their own locked down page in my sheet. OATH2 will allow us to individually authenticate and not have to enter in API keys.

    My issue:
    I’ve attempted to add in a custom OAUTH2 connection using Coinbase’s Authorize/Token urls:
    Authorize URL: https://www.coinbase.com/oauth/authorize
    Access Token URL: http://www.coinbase.com/oauth/token
    I created a Coinbase OAUTH app, and I used the redirect/callback URL for API Connect as described in this post.
    I created a custom API Connect OAUTH Connection and entered in my clientid/secret info after creating the Coinbase OAUTH2 app@Coinbase. (maybe that’s the problem, its not OAUTH2, but just OAUTH?)

    When I click the Connect button to authenticate, it appears to work – Coinbase pops up with my account and asks to give access. I accept.

    Then I get an error when it goes back to the callback URL (the callback url is in the address bar for this message)- It says this:
    Access Error
    An error has occurred: Error: Token response not valid JSON: SyntaxError: Unexpected token: I content: “Invalid request. Instead of a GET request, you should be making a POST with valid POST params. For more information, see https://developers.coinbase.com/docs/wallet/coinbase-connect“.

    I am not sure if I need to put the scope of what I want to access into the authorize url or not, but essentially the only information I want to access is in the wallet:buys:read scope.
    The url to access this is:
    https://api.coinbase.com/v2/accounts/:account_id/buys
    And each “account” is actually the “coin” wallet of the user, so I’d need to iterate through all of the accounts on the user, which is at this endpoint:
    https://api.coinbase.com/v2/accounts
    with this scope:
    wallet:accounts:read

    I tried to get as much info for you as possible so you didn’t have to re-learn everything I did.

    Please assist if you have the time to do so. I greatly appreciate any time you can afford to spend.

    (Coinbase integration guide here – https://developers.coinbase.com/docs/wallet/coinbase-connect/integrating)

    Reply
    • I think the main issue is that the Auth Code (used to then obtain the OAUTH token) is not returned as JSON, it is returned to the callback URL directly as a parameter. I tested pasting my authorize url into my internet browser by using the redirect url of “urn:ietf:wg:oauth:2.0:oob” and it shows the auth code in the title bar and in the URL itself.

      Is API Connect capable of grabbing the auth code without it being returned explicitly as JSON content?

      Reply
      • Hi Brandon! Thank you for all the detailed information, that helps with troubleshooting. API Connector’s custom OAuth2 connection expects the authorization code as a URL parameter so that shouldn’t be an issue. I tested and was able to authenticate as follows:

        1) created a new app here: https://www.coinbase.com/settings/api. This gave me the client ID and secret
        2) in API Connector, filled out the custom OAuth2 settings like this:
        Name: Custom Coinbase
        Authorization Base URL: https://www.coinbase.com/oauth/authorize?scope=wallet:accounts:read
        Token URL: https://api.coinbase.com/oauth/token
        Client ID:
        Client Secret:

        Once I did that I clicked connect and it seemed to work without any problem. I don’t have a Coinbase wallet but I ran a request to https://api.coinbase.com/v2/accounts and it pulled in data. Can you please try and see if it works for you?

  4. Hello! I have this client and they are using RetailExpress POS and this is the API documentation: https://developer.retailexpress.com.au/

    It seems that it requires OAuth 2.0

    Can you add this? Or help/guide me to do it?

    Thaaaank you so much. I’m a very big fan of this tool will be using these to all of my clients in the future

    Reply
    • Hi Jab! Thank you for the message. Unfortunately it looks like they’re using a non-standard mix of APIs keys + OAuth2, so it won’t directly work with API Connector’s OAuth2 manager (they require you pass an API key in the header to get your OAuth2 token). Therefore you will need to step through their process semi-manually, like this:
      1) register an application on their site to get an API key
      2) run a request to https://api.retailexpress.com.au/v2/auth/token. Under Headers, include Key = x-api-key, Value = your-API-key (substitute in your API key here). This request will return your token.
      3) To make new requests, keep that x-api-key header and add a new one of Key = Authorization, Value = Bearer your-token (substitute in your token here)
      4) Since the bearer token will continuously expire, you will always need to run that first request before you make a new request. You can set your headers to reference the updated token in your sheet, so you don’t need to manually update your request.
      It’s a little inconvenient compared to the normal process, but should work. Let me know if you get stuck or need further clarification.

      Reply
  5. ‘Request failed: Access not granted or expired. Please reconnect.’
    i got this message for Zoho Analytics after some time and my connection is expired, then i need to manually re-connect the connection,

    so is there any way to avoid this manual process??

    please help

    Reply
  6. Hi Ana,

    I try to connect to an affiliate network. Therefore I used your explanation in your comment to Jab by using the credentials in the ‘key’ and ‘ value’ fields in the header. That worked. But now I need to make a new request which is getting access to the affiliate programs based on a keyword. How to make a new request that follow up the first one (authorization)? This is the link of the affiliate program.

    https://wiki.awin.com/index.php/API_get_programmes

    Reply
    • Hey Michel, I checked their docs and it’s not the full OAuth2 process, it’s much simpler so you don’t need any of the instructions on this page.

      Under API Url Path, enter the API URL you’re interested in.

      Then, under headers enter Key = Authorization, Value = Bearer your_token

      Substitute in your token where it says your_token. You can get your token while logged in, they have some screenshots here: https://wiki.awin.com/index.php/API_authentication

      Please check if that works for you.

      Reply
  7. Hello, I’m curious if you could assist on the Snapchat Story Studio Analytics API? I keep getting “missing scope” when I follow the steps for the Custom API connector. Thank you!

    Reply
    • Sure, the scope should be snapchat-marketing-api. So the whole thing would be set up like this:
      Name: any name, e.g. Custom Snapchat
      Authorization Base URL: https://accounts.snapchat.com/login/oauth2/authorize
      Token URL: https://accounts.snapchat.com/login/oauth2/access_token?scope=snapchat-marketing-api
      Client ID & Secret: provided by Snapchat

      Let me know if you run into any issues.

      Reply

Leave a Comment

Table of Contents