Search API Connector Documentation

Print

Connect to an OAuth2 API

Last Updated On
byAna
< Knowledge Base

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. API keys are easy to use, as they can be simply entered as Header keys or URL query strings.

As an alternative to API keys, 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 install API Connector for a free trial or upgrade to access.

Contents

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 manually managing the process of exchanging & refreshing tokens
  • connect securely, without needing to enter sensitive access credentials.

Before You Begin

Click here to install the API Connector add-on from the Google Marketplace.

How to Connect

  1. To access the current list of integrated OAuth 2.0 platforms, click Add-ons > API Connector > Manage Connections, or open the Create screen and click the “Manage connections” link.
    oauth2-img1
  2. You will see a screen listing the available services.
    oauth2-img2
  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.
    oauth2-img3
  4. You’ll now see your new connection reflected in the list. This means you’ve now successfully connected via OAuth 2.0.
    oauth2-img4

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:
    oauth2-img7
  2. You will be presented with a screen containing input values for Name, Authorization Base URL, Token URL, Client ID, and Client Secret:
    oauth2-img8
  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 URL. This is the callback 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:
oauth2-img5

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

Notes

33 thoughts on “Connect to an OAuth2 API”

    • Hi Adam, thank you for the suggestion. IAP is something I really know nothing about. I’ve mostly been adding high-demand connections like Facebook and YouTube etc, so this one might make more sense as a custom OAuth2 connection that you add privately, but I will investigate.

      Reply

  5. Hey,

    I have a question about Connections. Is there a way to create a global connection for all the accounts editing the google spreadsheet? For example, we would like to create a Quickbook connection that can be used by all the editors to create requests. Thank you for your answer!

    Reply

    • Hi Erik! Thank you for your message. The OAuth2 connections are per user, since OAuth2 is an authentication framework based around allowing access only for the specific users that have authorized the application. If you would like multiple people to access the connection, you could either have each user authorize the connection separately, or you could create a shared gmail account for use with Sheets, or you could designate someone to set up / schedule requests and just give everyone else read access to the data. I hope that helps clarify, if not, please let me know.

      Reply

    • Hey David, I haven’t connected to the Google Ads API myself but I think you could do this by following Google’s documentation on how to get your OAuth2 details and connect to the API. I’ll probably go through this process myself and add it as a default connection.

      Reply

  7. I’m very new to this and trying to connect to Etsy.

    I уntered the following data in the “Add Custom OAuth” form:

    Authorization Base URL:
    https://openapi.etsy.com/v2

    Token URL:
    https://openapi.etsy.com/v2/oauth/request_token?scope=email_r

    Client ID:
    azm3uoqeh5glvuaqa1jj9XXX

    Client Secret:
    xsargf6XXX

    Then a page opened in a new tab with the following error:
    “API request missing api_key or valid OAuth parameters”

    How this can be solved? Any help appreciated.

    Here is Etsy page about their OAuth:
    https://www.etsy.com/developers/documentation/getting_started/oauth

    Reply

  8. Hi there – I’ve been trying to get a custom OAuth2 connection to work with Workflowmax, which is owned by xero. I see that you have a xero connector but it doesn’t seem to apply to workflowmax. Any tips on how I would configure a custom connector?

    So far I have a client id, and secret and I think I have the authentication URL right but i’m not sure how to build the token URL or how to use the token in the header of a subsequent request.

    Reply

    • Hey Jay, if you’re using OAuth2 you shouldn’t need to manually add any tokens to your headers. The authorization and token URLs should be provided in the Workflowmax docs (I just checked and it looks like authorization URL = https://login.xero.com/identity/connect/authorize?scope=workflowmax&offline_access and token URL = https://identity.xero.com/connect/token). Can you please try that and let me know how it goes?

      Reply

      • Thanks for your quick response!

        The two URLs you’ve identified are what I have configured so that’s good and I think it’s working. When I click on the ‘connect’ button it authenticates against xero and returns to the google sheet as expected.

        Given that i’m using the OAuth2 connector you indicated that I don’t need to do the token refresh. And of course, you’re right! I just re-read how to make calls to the API and I was missing a header for the tenant id. I’ve added that and it’s working as expected now.

        Thanks for your help!

    • 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

  10. Hello. I suggest a connection to Mercadolibre API, the most important market place in Latinamerica and one of the largest of the world.

    Reply

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

    • Hey Paul, I’m not sure I totally understand as that sounds like all the parts to a standard OAuth2 flow. Which part is missing? But in any case, 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. You can see an example of manually going through an OAuth2 flow in this article.

      Reply

  12. 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, and I must admit I’m not totally sure what you’re trying to do. Generally you don’t need to pass in the value for the ’email’ scope yourself, 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. And please let me know if I’ve misunderstood anything on my side.

      Reply

  13. 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?

Leave a Comment