Authentication

Authentication

The first part of connecting to an external API is to authenticate (unless you are connecting to a public API that doesn't require authentication).

This can in many ways be compared to logging into a an app – by providing a username and password you authenticate with that app and the app can proceed to determine what kind of resources you should be given access to.

An API call works in the same way in principle: by providing some authentication you are letting the server know who you are so that it can respond with the appropriate data. As we explored in our article on what RESTful APIs are, each and every API call are completely independent of each other – in other words, you must authenticate for every call that you make. The server does not "remember" who you are, but verifies the identity of every client who makes a request.

This is why we first need to add the authentication to any API provider in the API Connector; this way Bubble can automatically send the correct authentication along with every call, so that you only need to set it once.

API Keys

Many APIs use what's called an API key. This is a securely generated token that serves as both a username and a password.

API key security in the API Connector

API keys that you add to the correct fields in the API Connector are not visible to your app's Users or other Bubble users. They are stored in an encrypted state on Bubble's server.

API calls from the API Connector are routed through Bubble's server, which means that all the authentication methods below offer the same level of added security. RESTful API calls are sent via the HTTP protocol, which in modern web systems is encrypted with HTTPS during transit.

Development keys and live keys

Many API providers allow you to generate to sets of keys: one for testing and one for the live version of your app (often called production).

It's best practice to use these keys as intended: Bubble lets you add each of the keys to the development and live version of your app and will automatically use the correct key depending on which version you are running.

Designing the calls starts with the authentication method, which will sign the calls in Run-mode. Authentication can be done in several, standard, ways. Note that whenever you're building an API connection with some keys, you will need to enter some actual keys to test. These keys are only saved to help you work on your plugin. They will never get sent to users that use your plugins. Instead, they will have to enter their own API keys in the Plugins tab of the editor.

Authentication methods

There are many different ways to authenticate, and which method to use is specified by the API provider in their documentation. Below we will go over the different methods that Bubble supports, which cover most RESTful API providers.

The different authentication methods are visible in the dropdown next to the API name:

None or self-handled

Some providers require no authentication. This can also be the case if you are connecting two systems that you both control. By selecting this option Bubble will not send any authentication with the call.

You can also handle authentication with custom parameters and handlers but this should be done with caution.

Private key in header

With this method, the key is added to the header of all requests. Most providers name the parameter Authorization, but you can give the parameter a custom name as specified in the external API documentation if needed.

1. The first is the name of the parameter the server expects. Check the external API documentation for this.

2. The third is the API key for the live version of your app

3. The second is the actual API key for the development version of your app

What does a private key in the header look like?

Authorization: Bearer <token>

The example above would be one row of the header – it also contains other data. The <token> is replaced by the actual token without the <> signs.

Private key in URL

The Private key in URL option lets you add the key in the URL of each call.

1. The first field is the name of the key, which specifies how the authorization parameter key should be named in the URL. You will need to check the API provider's documentation for how they want the key to be named

2. The second is the actual API key for the live version of your app

3. The third is the API key for the development version of your app

   

What does a private key in the URL look like?

With this information, Bubble will add a parameter to the URL of each call, like the example below:

GET https://myapp.bubbleapps.io/version-test/api/1.1/obj/datatype/UID?private-key=this-is-the-live-key

In this example we are using the GET method to get information about a specific data type in a Bubble app..

HTTP Basic Auth

The HTTP Basic Auth method is a bit different than the two previous in that it works by sending the client's username and password in the header of the request. The username and password is often encoded using Base64.

A username/password will be sent with each request, according to the HTTP Basic Auth protocol (see this).

What does HTTP Basic auth look like in the header?

The HTTP Basic auth method looks a lot like the private key in header method:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The "dXNlcm5hbWU6cGFzc3dvcmQ=" string is an encoded version of the string "username:password".

Oauth2 Password Flow

In the Oauth2 Password Flow method you send a username and password to the external app, and the app authenticates using those credentials. The external server generates a token that can be used for subsequent requests until it expires or is revoked (at which point Bubble will renew it for you).

Your app needs to call a specific endpoint to get the returned token, and you need to consult the external documentation to determine what the URL of this endpoint is.

How secure is this method?

From a technical perspective it's safe to send a username and password via an encrypted HTTPS request. Still, this method should be used with some caution since any time you share a username and password with a third party you are opening up to potential misuse and must place your trust in that third party to maintain their security in the exchange.

Oauth2 Custom Token

This flow is similar to the Oauth2 Password Flow but offers more customization in case the API provider is not following the common standard in the method above. The token will be added to calls as a Bearer Token and will automatically be renewed when necessary.

Note that to function, the token should be returned as an object with two keys (at least), access_token and expires_in .

Oauth2 User-Agent Flow

The Oauth2 User-Agent Flow is the most widely used to to connect when you use the API on behalf of the User (meaning that the User is logging in using their own account to the third-party service, such as their Facebook or LinkedIn profile). This method takes a few more steps than the previous ones, as you will in practice need to authenticate with two accounts:

1. First, you connect to the external app using credentials that the app has generated for you.

2. Then, the User authenticates themselves with their own credentials on a page hosted by the external app and authorizes that your app is given access. Oftentimes they will already be logged in and simply need to authorize the request.

3. The API Connector then makes a call to a specific endpoint to the newly generated token that provides access to subsequent calls

4. Finally, the API Connector connects to another endpoint using the token to authenticate and getting access to the User's profile information (such as email, profile photo, etc). The information available depends on the service and sometimes the personal settings of the User in the third-party system.

Scope

The Scope setting determines the level of permissions you are asking for from the external server. Scope settings and how they are specified can vary from provider to provider, so the entries in the list below should be considered examples to illustrate what the scope setting is for:

Scope parameters are usually separated by a space as in the example below:

readonly email

Your app's credentials

As we explored above, the Oauth2 User-Agent Flow involves first authenticating your app as the client making the request. While these settings can vary depending on the API provider, the most widely used method is to provide two keys for authentication:

Using App ID and App Secret together provides a secure way for the API provider to identify the client (your app) and ensure that it is who it claims to be – all without exposing the two keys to your app's Users.

The two keys are usually generated in the settings of the API provider.

JSON Web Token

Some services use this more advanced protocol to handle scope and permissions. This is usually for enterprise-type services, like Box or Google Cloud.

To authenticate with a service using the JSON Web Token method, you need:

• The email that's used to set up the account with the third party

• The endpoint that returns the token (which you'll find in the external API documentation)

• The private RSA key that the service has provided

The private key needs to be formatted as the below example, including the '-----BEGIN RSA PRIVATE KEY-----' and '-----END RSA PRIVATE KEY-----':

-----BEGIN RSA PRIVATE KEY-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
................................................................
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END RSA PRIVATE KEY-----

Client-side SSL certificate

Using a Client-side SSL certificate is not as widely used as some of the other methods, but it's sometimes used in internal enterprise networks.

A client-side SSL certificate servers as a digital certificate that your app can you to authenticate with the server. It consists of two parts: The Certificate file content is the data contained in a digital certificate file (also known as a public key certificate). It contains information about the identity of the certificate holder (your app), such as a name and public key. It also holds information about the certificate issuer (the server you are connecting to), such as its name and digital signature.

The Key file content is the data contained in a private key file. It's used in conjunction with the public keys of both parties to encrypt and decrypt information.