API Connector Documentation

Print

Connect to an OAuth API

Last Updated OnMarch 16, 2024
byAna
< Knowledge Base

API Connector includes many preset OAuth2 connections. For these preset connections, you can securely authenticate yourself by clicking a Connect button rather than retrieving and entering an API key or other credentials.

You may also add your own custom OAuth2 connections for APIs we haven't integrated.

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 by logging in to an application instead of entering their credentials.

You've probably encountered OAuth2 before. It's the technology behind most "sign in with X" authorization flows.

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 or share sensitive access credentials.

How to Connect

  1. Whenever you select an OAuth connection, you'll see a blue Connect button. These connections are available when you create a request and on the Manage Connections screen.
    presetoauth-connect
  2. Whichever flow you choose, these OAuth buttons will direct you to the target site, where you will be prompted to connect your account.
    oauth2-img3
  3. Once you accept, API Connector will display your connection status and keep you connected.
    presetoauth-connected
  4. Now you can enter your request details and choose your connector to make your request:
    presetoauth-response

How to Add Multiple OAuth Connections

In some cases you may log into an application or website with multiple email addresses, e.g. one email address for one of your Etsy stores, and a different email address for another.

  1. Wherever you can add OAuth connections, you can add in multiple connections. When creating a custom or preset request, click the + icon. On the Manage Connections screen, add new OAuth connections by clicking Connect in the Add New OAuth section.
    presetoauth-addmulti
  2. By default, the new connection will take the name of the root connection with a "-2" (or "-3", "-4", etc) appended at the end, e.g. "Google Analytics-2". Optionally rename the connection from the Manage Connections screen. This will help you identify which OAuth connection is associated with which account. (Only multi-OAuths can be renamed, not the original root connection.)
    presetoauth-renamemulti
  3. This new connection will be available wherever OAuth is available.
    presetoauth-selectmulti
  4. To remove connections from the dropdown list, open the Manage Connections screen and click the logout icon.
    presetoauth-logoutmulti

Notes

  • Multiple instances of OAuth2 connections are saved only to the sheet in which they're created. Unlike the original root connections, they won't be available in other sheets.
  • When you connect your sheet to an API via OAuth2, only your account can run the queries. If other people have Edit access to your sheet, they can see and edit your requests, but they need to authenticate through their own accounts to run them.
  • Some APIs provide multiple methods of connecting, e.g. either an API key or OAuth2. If you're using the OAuth2 method, just skip their instructions for adding an API key. You don't need to enter any authentication-related headers if you're using OAuth2.

45 thoughts on “Connect to an OAuth API”

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

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

    Reply

    • Thanks, I looked into this but couldn't seem to create a connection without being a resident of their supported countries. So for now I suggest creating your own custom OAuth connection, just register an app on their site and they'll give you the client ID and secret. Then the Auth URL is https://auth.mercadolibre.com.ar/authorization (change 'ar' based on the country domain you use with them), and the Token URL is https://api.mercadolibre.com/oauth/token. Just enter those 4 values into API Connector's custom OAuth form to connect.

      Reply

      • Hello Ana. I tried that method but it didn't work. I got: "error=strict_redirect_uri_mismatch". The redirect uri used was: "http://localhost:3000".
        Any idea about what could be the problem? Thank you.

      • You'll need to use API Connector's redirect URL rather than your own localhost URL. You can find it here (check the section on configuring an app)

    • I just checked this out and it was pretty straightforward to set up OAuth, I was able to connect and retrieve test data using our OAuth connection manager. However, the confusing part is that they don't seem to provide any simple mechanism for an individual merchant to get their own data, instead they require that you set up a sandbox account, set up a test app, then get approved for a production account, then create a production app to be published in their marketplace, etc. I just applied for a production account and will see how that goes.

      Reply

    • Thanks for the suggestion. In the meantime you could set up a custom OAuth connection. Based on their docs, you'd get your client ID and secret by registering an app here, and then the auth URL would be https://api.getbase.com/oauth2/authorize?scope=read and token URL would be https://api.getbase.com/oauth2/token

      Reply

    • Not really sure, I just searched online and couldn't find any link to API documentation for Titan K-12. Do you have a link? If so I can take a look.

      Reply

      • I'm having troubles locating it as well since it is a relatively new software system. I'll let you know if I find it, thanks though!

  11. I'm getting closer: I can now connect, but when I run the request, I get this message:

    1) getemail: Request failed: Access not granted or expired. Please click Manage Connections and check OAuth2 connection status.

    I don't understand what I'm being asked to do.

    Reply

    • Hi Brian, that error message means you're not connected to the OAuth connection you're using.
      To connect, please click the Manage connections link in the main menu or on the Create screen. From here, you can scroll down the screen and click Connect if you're not already connected.

      If you're still stuck, can you please send me a screenshot of what your full request looks like?

      Reply

    • Sorry, I don't think you can connect to either through a custom OAuth connection. Microsoft Ads still uses the very old SOAP protocol for connecting to APIs, rather than the current standard of entering URLs to connect, so there's no way to access their data points through our connector. And for Amazon Ads, I believe they require a complex "signature" to connect rather than common standards like OAuth or API tokens. Basically both of these applications have more complexity than most APIs and therefore require custom code. We do plan to add support but it's not on the immediate roadmap, apologies for the inconvenience but I hope that clarifies.

      Reply

  17. When connecting to the teamleader API, a redirect URL is expected to retrieve the authorization code.

    I can't seem to find a way how to add these parameters to the OAuth connection. Without this I get an error.

    {"errors":[{"code":3,"title":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.","status":400,"meta":{"type":"invalid_request","hint":"Check the `redirect_uri` parameter"}}]}

    Reply

Leave a Comment

Jump To