Authenticating your API requests

How to authenticate your API requests and understand the different authentication methods.

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:

API Key
Bearer
Basic
OAuth

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

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

Action 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 key

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

URI 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 authentication

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))

Additional 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 authentication

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:"))

OAuth

Not 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:

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.
Get an Access Key by using the UI of the service you want to use.
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.