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 redirect or callback URL. This is the 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

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

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

    Reply

  10. 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, 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 and go through the OAuth2 flow manually.

      Reply

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

  14. ‘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

Leave a Comment