Authentication
This section covers the different authentication methods the API Connector offers.
Authentication is the process of identifying who a is in order to determine what they have access to on the server.
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 keys are considered sensitive data and should never be shared with anyone. Treat it like you would a username and password. Do not store API keys in Option Sets, page elements or on-page workflows as they will become visible in the client-side code of your application. If you suspect that someone has access to one of your API keys, most API providers will let you generate a new one.
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 , which in modern web systems is encrypted with during .
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.
In this article we use multiple fairly technical terms to explain how the different authentication methods work. You may find our API Glossary useful if there are words or terms you're unfamiliar with. If you are new to API's you may also find our Introduction to APIs and What are RESTful APIs articles useful.
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 visislbe 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.
We do not recommend handling authentication yourself as this comes with a risk of exposing your API keys and the connection. Bubble's built-in authentication system is designed to keep your data and connections secure.
Private key in URL
The Private key in URL option lets you add the key in the URL of each call.
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
The second is the actual API key for the live version of your app
The third is the API key for the development version of your app
What does a private key in the header look like?
With this information, Bubble will add a parameter to the URL of each call, like the example below:
In this example we are using the GET method to get information about a specific data type in a Bubble app..
Private key in header
With this method, the key is added to the 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.
The first is the name of the parameter the server expects. Check the external API documentation for this.
The third is the API key for the live version of your app
The second is the actual API key for the development version of your app
What does a private key in the header look like?
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.
The actual key name in the example above can look different depending on the API provider. Consult their documentation to find the right formatting for their particular setup.
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 .
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:
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.
You can read more about the mechanics of this authentication type in the OAuthLib documentation.
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
Setting up the Oauth2 User-Agent Flow can be a bit complicated if you are not familiar with APIs. There are many plugins that can set up the connection for you without having to go through the API Connector. Article: Finding API-related plugins
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:
First, you connect to the external app using credentials that the app has generated for you.
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.
The API Connector then makes a call to a specific endpoint to the newly generated token that provides access to subsequent calls
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 example | Description |
|---|---|
admin | Full administrative access to make changes to a User's resources |
Access to the User's email address. | |
profile | Access to the User's basic profile information such as name, email and profile picture. |
read or readonly | Permission to read but not modify a user's resources. |
write or readwrite | Permission to read and modify a user's resources. |
Scope parameters are usually separated by a space as in the example below:
Accessing a third-party User profile often means accessing that User's personal information. To respect the User's privacy and minimize the risk of personal data being misused or mishandled, it's important to only request the minimum level of access necessary for your app to work.
Your app's credentials
As we explored above, the Oauth2 User-Agent Flow involves first authenticating your app as the 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:
| Key | Description | |
|---|---|---|
Client ID | This string identifies who you are (as the client), which lets the server proceed in determining what you should be given access to. | The client ID is not considered sensitive data. |
Client secret | This string is used to cryptographically sign the token request and prove that the request is authentic (since only your app would have that key) | The client secret key should be kept secret and should not be shared or exposed in any way |
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-----':
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.
Last updated
