Arrow
Advanced

Authenticating your API calls

Learn about authentication in APIs: the different types, how to use them, and how to read API documentation to find what you need.

So, you want to work with an API in Rows? Well, from our side, we’ve made that as simple as it could be. But the trouble usually lies with understanding APIs themselves - that’s why we’ll take you through all the basics in the next few articles on how to work with them.

In this lesson, we’ll go over:

  1. Some basic API terms
  2. How to read API Authentication documentation
  3. How to use the four common types of documentation

Ready? Let’s go 🚀!

Basic termsAnchor Icon

What’s an API?

An API is basically a little program that applications create so that other applications (or people) can interact with them and their data.

Why do you need to know this?

APIs let you send and retrieve data from anywhere in the world - and the more information you can access, the better your conclusions can be.

How do I access that data?

You access API data by using something called HTTP methods. At Rows, we have three HTTP functions:

  • GET, to get information from a service
  • PUT, to replace information in a service
  • POST, to send new information to a service

Each time you use one of these methods, you’re making a request.

How do I know how to use them?

You'll need to read the documentation for the API you want to use. Unfortunately, each API is usually written slightly differently, which can make things a bit confusing. But with these next few articles, we’ll show you what you need to look for in these docs in order to be able to understand just what you need to do and get working with an API.

Where do we start?

With Authentication :) Without Authentication, most APIs won't let you do anything.

AuthenticationAnchor Icon

Before you can access pretty much any API, you need to know how to authenticate your request.

There are four popular types of authentication that you’ll read about:

  1. API Key
  2. Bearer
  3. Basic
  4. OAuth

Note IconAPIs and authentication

There are some public APIs that let you request data without having to use authentication. However, APIs that contain some kind of private data or bill you according to how much you use it will require authentication.

How to know which one to use?

To know exactly which authentication method the service requires, you need to go to the documentation of the API you want to use and look for the Authentication section. Have a look at the table below and you’ll get what to look for.

Typetl;dr
API KeyLook for “API Key” and something along the lines of key=<APIKEY>.
Bearer AuthenticationLook for Authentication: Bearer <API KEY>.
Basic AuthenticationLook for username:password or Authentication: Basic username:password.
OAuth2.0Just look for OAuth 🙂.

Tip IconAction URL and Headers

You’re going to hear action_url and headers mentioned in the article. We’ll talk about it more in-depth in our next one, however, for now, just think of it this way:

The action_url is the URL address that we communicate with.

The header is an extra parameter that we sometimes send with additional information (often for authentication).

API keyAnchor Icon

An API key is possibly one of the simplest methods to authenticate. Before you can though, the service you want to use will ask you to sign up and then generate the API key.

What does it look like?

www.url.com/?ApiKey=<Your API Key>

How to know?

The documentation will usually mention "API Key", or the code example will be similar to the example above.

How to add it to a Rows web function?

You'll just need to add it to the action_url as the URI query (check the exaple above). If you come across APIs that use this type of authentication, you’ll need to check their API documentation to see what the actual key name is. Sometimes it’s called api-key, other times it’s token, and so on and so forth.

Note IconURI Query

A URI query is basically everything after the question mark ? in the URL. It follows a key=value format.

You join more query parameters with a &:

url.com/?key1=parameter1&key2=parameter2&key3=parameter3

URL and API key encoding
In some cases, you might need to encode your URL or API key.

If you need to encode your URL, just paste it into this URL encode service and copy the encoded URL into Rows.

If you need to Base 64 encode your API key, use our BASE64 function. Like so:

="http://api-you-want-to-access/?apikey="&BASE64("YourApiKey")

Bearer authenticationAnchor Icon

Bearer authentication uses something called an authorization header that bears your ID (usually your API key).

What does it look like?

"Authorization": "Bearer <YOUR API KEY>"

How to know?

The documentation will usually mention the word "Bearer", or the code example will be similar to the example above.

How to add it to a Rows web function?

You just need to add the following as the header parameter:

PAIR2JSON("Authorization",("Bearer "&myAPIKey))

Note IconAdditional header elements

If the API requires you to add more elements in the header, you just need to add them to the PAIR2JSON() function. For example, some require that you also pass in the format of your requests. In that case:

PAIR2JSON("Authorization",("Bearer "&myApiKey),"format","JSON")

Basic authenticationAnchor Icon

Basic authentication requires you to Base-64 encode either a username:password string or the API key followed by a colon (apikey:).

What does it look like?

"Authorization": "Basic <BASE-64 ENCODED API KEY>"

How to know?

Well, aside from the documentation mentioning Basic authentication, if you ever see something like this:

  • Username:password
  • Apikey:X
  • Apikey:

Then it's Basic Authentication 😉.

How to add it to a Rows web function?

You just need to add one of the following as the header parameter, depending on the API documentation:

Username:password
PAIR2JSON("Authorization","Basic "&BASE64("username:password"))

API Key
PAIR2JSON("Authorization","Basic "&BASE64("APIkey:"))

OAuthAnchor Icon

Caution IconNot for the faint of heart

Authenticating with OAuth is not that easy - it's usually something that developers tackle. If you're set on using a service with OAuth, but are running into trouble, ask in our Forum. Someone will surely be able to help you out 😉.

OAuth is a bit more complicated as it requires a couple of steps before accessing the API with requests. If you want to learn more about OAuth, there’s a great article here that explains things nicely and simply.

In a nutshell, to use OAuth in Rows:

  1. Get the necessary credentials (client ID and client secret). It’s not uncommon that you’ll need a developer account to get all the credentials.
  2. Get an Access Key by using the UI of the service you want to use.
  3. Use the Access Key as your API key in one of the three authentication methods above. Check the service's API documentation to be sure which one to use.

Refresh Tokens
With OAuth, your Access Key usually expires after some time, however, you can always refresh it. To be able to do it in Rows it really does depend on the API and whether or not you can request a refresh token by just using your current Access Key.

Up nextAnchor Icon

OK - so we’ve got authentication down. Now, let’s go on to the next lesson and learn how to get data from any API.