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 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 client in every 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.

An API token or API key is a string of characters that identifies your app to an external service and grants it permission to make API calls. Think of it as a key: when you include the token with a request, the service uses it to confirm who you are and what you're allowed to do.

API tokens serve the same basic purpose as a username and password, but they're designed for machine-to-machine communication. They're typically long, random strings that are hard to guess, easy to generate and revoke, and can often be scoped to specific permissions, such as read-only access or access to a particular part of the service.

Each token is issued by the API provider and tied to your account. Some providers offer a single token per account, while others let you generate multiple tokens with different permissions, so you can use a separate one for each app or environment. If a token is exposed or no longer needed, it can be revoked at any time without affecting your account as a whole.

The API Connector is built to keep your credentials out of the user's browser. 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. By default, all calls are routed through Bubble's server, which means your API keys and other sensitive values are never sent to the client. The user's browser only ever sees the data it needs to display, never the credentials used to fetch it.

RESTful API calls are sent from the server using the HTTP protocol, the same protocol that web browsers use to load websites. In modern systems, these calls are encrypted in transit using HTTPS, which protects the contents of the request and response from being intercepted or read by anyone on the network between the Bubble server and the API server.

This server-side routing is the main reason the API Connector is the recommended place to store and use API keys in your app. Several built-in safeguards work together to keep credentials secure:

Many API providers issue two separate sets of credentials: one for development and testing, and one for production use. Keeping these environments separate is a standard practice that helps you build and test safely without affecting real users or real data.

Development keys are tied to a sandbox or test environment provided by the service. Calls made with development keys don't affect real data or trigger real transactions. For example, Stripe's test keys let you simulate payments and customer creation without actually charging cards.

Live keys are tied to the production environment, where every call has real consequences. A payment processed with live keys charges a real card, an email sent with live keys reaches a real inbox, and a record created with live keys appears in your actual account data.

Bubble apps have separate development and live environments, which makes it natural to use a matching pair of keys. In many scenarios, It's best practice to use these keys as intended: in many scenarios, 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.

Things to keep in mind

Authentication is how an API verifies who's making a request. When your Bubble app sends a call to an external service, the service needs some way to confirm that the request is coming from an authorized source and to determine what that source is allowed to do.

Different providers use different authentication methods, and the right method for your app depends entirely on what the provider supports. Some services use a single API key sent with every request, while others rely on more involved flows that exchange credentials for short-lived access tokens. None of these methods are inherently better than the others. They're designed for different use cases and trade off simplicity, flexibility, and security in different ways.

The API Connector supports the most common authentication methods used across modern APIs. The provider's documentation will tell you which method to use and how to generate the credentials your app needs.

This section covers each authentication method the API Connector supports, what it looks like in practice, and when you might encounter it.

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

The None or self-handled option indicates that no authentication is configured at the collection level. This is used for APIs that don't require authentication at all, or for cases where you want to handle authentication manually on each individual call.

This option is useful in two main scenarios:

To use this option, select None or self-handled from the Authentication dropdown in the collection's settings. No additional fields appear, since no authentication is configured at this level.

If the API requires credentials, you'll need to add them as headers or parameters on each call. Mark any sensitive values as Private to keep them on the server.

The Private key in header method authenticates requests by including a key in the request header. The provider reads the header on each call to verify the request.

The key is sent as part of the HTTP headers, typically in an Authorization header. Many APIs expect the key to be prefixed with a scheme such as Bearer, followed by the actual key value.

Sending the key in the header rather than the URL is generally more secure, since headers aren't logged in the same way URLs sometimes are. This is the recommended method for most modern APIs that use a single key for authentication. Bubble routes both methods through the server, minimizing the risk?

This method is widely used across modern APIs. Most services that issue an API key or bearer token expect it to be sent in the Authorization header. Examples include OpenAI, Stripe, SendGrid, and many others.

To configure Private key in header, select it from the Authentication dropdown in the collection's settings. The following fields will appear:

Once configured, the API Connector adds the header to every call in the collection automatically.

The Private key in URL method authenticates requests by including a key as a parameter in the URL itself. The provider checks the key in the query string to verify the request and determine what it's allowed to do.

The key is appended to the URL of each request, typically as a query parameter such as ?api_key=your_key_here. The provider reads the key from the URL and uses it to authenticate the call.

This method is one of the simplest authentication options, but because the key appears in the URL, it can be logged by servers, proxies, or browser history if exposed to the client. Bubble automatically routes the call through the server to minimize this risk.

This method is common with simpler APIs, public-facing data services, and APIs where a single key is used to identify the entire account. It's often used by weather services, geocoding APIs, and other read-only data providers.

To configure Private key in URL, select it from the Authentication dropdown in the collection's settings. The following fields will appear:

HTTP Basic Auth is one of the simplest authentication methods. The client sends a username and password with every request, encoded as part of the request header. The server checks the credentials against its own records and allows or denies the request based on the result.

With Basic Auth, the username and password are combined into a single string, encoded in base64, and sent in the Authorization header of every request. The format looks like:

For example:

Despite the encoding, base64 is not encryption. Anyone who intercepts the request can decode the credentials, which is why Basic Auth should only be used over HTTPS. The encryption provided by HTTPS is what keeps the credentials safe in transit. Bubble maintains HTTPS automatically.

Basic Auth is common with older APIs, internal services, and some lightweight integrations. It's straightforward to implement and doesn't require token exchanges or redirects, which makes it appealing for simple use cases.

Most modern public APIs have moved to token-based authentication for added flexibility and security, but Basic Auth remains widely supported and is still the right choice for many services.

To configure HTTP Basic Auth, select HTTP Basic Auth from the Authentication dropdown in the collection's settings. The following fields will appear:

The exact values come from the provider, typically as part of setting up API access for your account. Once configured, the API Connector encodes and sends the credentials with every call in the collection automatically.

The OAuth2 Password Flow is an authentication method where the client exchanges a username and password directly for an access token. Once the token is issued, it's used for all subsequent requests instead of the original credentials.

The flow is straightforward compared to other OAuth2 methods. The client sends the user's username and password to the provider's token endpoint, along with credentials identifying the app itself. If the credentials are valid, the provider returns an access token that the client uses for future requests.

The typical sequence looks like this:

Unlike the User-Agent Flow, this method doesn't involve redirecting the user to the provider's login page. The credentials are passed directly through the API, which is why it's typically used in trusted environments where the app and the service share a close relationship.

This flow is most common with internal APIs or services where the app is trusted enough to handle user credentials directly. It's also used in some legacy systems and APIs that haven't adopted more modern OAuth flows.

The OAuth2 Password Flow has fallen out of favor for public-facing integrations because it requires the app to handle the user's password directly, which is generally less secure than redirect-based flows. Most modern public APIs use the User-Agent Flow or other authorization code flows instead.

You can read more about the mechanics of this authentication type in the OAuthLib documentation.

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.

To configure OAuth2 Password Flow, select OAuth2 Password Flow from the Authentication dropdown in the collection's settings. The following fields will appear:

The exact values for each field come from the provider's documentation. Once configured, the API Connector exchanges the credentials for an access token automatically and includes it with every call in the collection.

The OAuth2 Custom Token method is a flexible authentication option that lets you build a custom token request when the provider doesn't fit one of the standard OAuth2 flows. Instead of following a predefined pattern, you define the exact request that the API Connector sends to retrieve the access token.

Some providers implement OAuth2 in ways that don't match the standard flows. They might expect a different request format, custom headers, or a specific JSON body structure when requesting a token. The custom token method gives you full control over how that request is made, so you can match whatever the provider requires.

Once the access token is received, it's used for all subsequent calls in the collection, the same way it is with other OAuth2 methods.

This method is most useful when working with providers whose token request doesn't fit the User-Agent Flow or Password Flow. It's also helpful when integrating with internal APIs or services that have their own conventions for token issuance.

If the provider's documentation describes a token request that doesn't match any of the standard OAuth2 patterns, the Custom Token method is usually the right choice.

To configure OAuth2 Custom Token, select OAuth2 Custom Token from the Authentication dropdown in the collection's settings. The following fields will appear:

The exact values for each field come from the provider's documentation. Once configured, the API Connector sends the custom request to retrieve the access token and includes the resulting token with every call in the collection.

The OAuth2 User-Agent Flow is an authentication method used when a user needs to grant your app permission to act on their behalf with an external service. Unlike methods that authenticate the app itself, this flow authenticates an individual user and returns an access token tied to that user's account.

The flow is built around redirecting the user to the provider's login page, where they sign in and approve the requested permissions. Once they approve, the provider redirects them back to your app with an access token. Your app then uses that token to make calls on the user's behalf.

The typical sequence looks like this:

This flow is common with services that hold user-specific data, such as social media platforms, calendar services, email providers, and cloud storage tools. It's the standard way for apps to access data tied to a specific user without ever handling that user's password.

For example, an app that integrates with Google Calendar would use this flow to let each user connect their own calendar, rather than using a single shared account.

To configure OAuth2 User-Agent Flow, select OAuth2 User-Agent Flow from the Authentication dropdown in the collection's settings. The following fields will appear:

The exact values for each field come from the provider's documentation, typically as part of registering your app with the service.

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:

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.

Testing the connection

After configuring the fields, the API Connector requires you to authenticate at least once in run mode before the connection can be used. To do this:

Once the access token is received, the connection is marked as valid and calls can be set up against it.

A JSON Web Token, or JWT, is a compact, signed token that carries information about the client making the request. Unlike a simple API key, which is just a random string, a JWT is a structured piece of data that includes claims about who the client is, what it's allowed to do, and how long the token is valid.

How it works

A JWT is made up of three parts, separated by dots:

When the client sends a request, it includes the JWT, typically in the Authorization header. The server verifies the signature to confirm the token is valid, reads the claims, and decides whether to allow the request.

Because the token is signed, the server doesn't need to look it up in a database. The information needed to authorize the request is contained in the token itself.

JWTs are commonly used by services that need to encode user-specific information into the token, such as APIs tied to authenticated user sessions. They're also widely used in modern identity providers and microservice architectures.

If the provider uses JWTs, their documentation will explain how to generate the token, what claims to include, and which signing algorithm to use. JWTs often have a limited lifespan, so check the provider's documentation to see how long tokens remain valid and whether they need to be regenerated periodically.

When using JWT authentication, the token is sent in the Authorization header of the request. Most providers expect the token to be prefixed with Bearer and a single space, followed by the JWT itself.

The header value should usually follow this format:

For example:

To configure JWT authentication, select JSON Web Token from the Authentication dropdown in the collection's settings. The following fields will appear:

Client-side SSL certificate authentication uses a digital certificate to verify the identity of the client making the request. Instead of sending a token or password, the client presents a certificate that the server checks against a list of trusted certificates. If the certificate is valid and trusted, the request is allowed.

In a standard HTTPS connection, the server presents a certificate to prove its identity to the client. With client-side SSL, the process works in both directions: the client also presents a certificate to prove its identity to the server. This creates a two-way trust relationship.

The certificate is typically issued by a certificate authority or generated by the provider, and it's tied to your account or organization. As long as the certificate is valid, the client is authenticated without needing to send any additional credentials with each request.

Client-side SSL certificates are most common with enterprise and financial APIs where strong identity verification is required. Banks, payment networks, healthcare systems, and government services often use this method because it offers a high level of security and doesn't rely on credentials that can be intercepted or guessed.

If a provider uses client-side SSL, their documentation will explain how to generate or request a certificate and how to configure it for use.

To configure client-side SSL certificate authentication, select Client-side SSL certificate from the Authentication dropdown in the collection's settings. The following fields will appear:

Both values come from the provider, typically as part of setting up API access for your account. Once configured, Bubble's server presents the certificate and key during each request, authenticating the call without exposing either value to the client.