Authentication
This section covers the different authentication methods the API Connector offers.
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 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 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.
API tokens
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.
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
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:
Authentication is configured at the collection level. Tokens and other credentials are stored once and used across all calls in the collection, without ever being passed through the client.
Private parameters stay on the server. Any parameter marked as Private is added to the request from Bubble's server, not the browser.
Development keys and live keys
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.
What each set is for
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.
Using both in your Bubble app
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
Never use live keys in development. It's easy to forget which keys are in use and accidentally trigger real transactions or send real messages during testing. Use development keys whenever you're building or experimenting.
Treat live keys with extra care. Live keys have direct access to real data, real money, and real users. They should be rotated regularly and revoked immediately if exposed.
Confirm which keys are active before deploying. Before pushing changes to your live environment, double-check that the live keys are configured correctly. Going live with development keys will cause calls to fail in production.
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.
Authentication methods
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:
None or self-handled
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.
When you'll encounter it
This option is useful in two main scenarios:
Public APIs. Some APIs don't require authentication, such as open data services, public weather APIs, or read-only endpoints that return general information. In these cases, no credentials are needed and the API can be called directly.
Custom authentication setups. Some APIs use authentication methods that don't fit any of the predefined options, or require credentials to be assembled dynamically. In these cases, you can leave authentication set to None and configure the necessary headers or parameters on each call individually.
Setting it up in the API Connector
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.
We recommend using built-in authentication methods to avoid the risk of accidentally exposing your API keys or other data. Bubble's built-in authentication system is designed to keep your data and connections secure.
Private key in header
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.
How it works
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 methdods through the server, minimizing the risk?
When you'll encounter it
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.
Setting it up in the API Connector
To configure Private key in header, select it from the Authentication dropdown in the collection's settings. The following fields will appear:
Key name
The name of the header used to send the key. Most providers use Authorization, but check the documentation for the exact value.
Private key
The key value used to authenticate against the provider. If the provider expects a prefix such as Bearer, include it before the key, separated by a space.
Development key value
An optional key used in your development environment, if the provider issues separate credentials.
Once configured, the API Connector adds the header to every call in the collection automatically.
Private key in URL
Including the private key in the header is a more secure method compared to embedding it in the URL. For enhanced security in your transactions, we recommend opting for the Private Key in Header method whenever possible.
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.
How it works
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.
When you'll encounter it
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.
Setting it up in the API Connector
To configure Private key in URL, select it from the Authentication dropdown in the collection's settings. The following fields will appear:
Key name
The name of the URL parameter used to send the key. The exact name comes from the provider's documentation, such as api_key or token.
Private key
The key value used to authenticate against the provider.
Development key value
An optional key used in your development environment, if the provider issues separate credentials.
Once configured, the API Connector appends the key to the URL of every call in the collection automatically.
HTTP Basic Auth
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.
How it works
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.
When you'll encounter it
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.
Setting it up in the API Connector
To configure HTTP Basic Auth, select HTTP Basic Auth from the Authentication dropdown in the collection's settings. The following fields will appear:
Username
The username used to authenticate with the provider.
Password
The password used to authenticate with the provider.
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.
Things to keep in mind
Both the username and password are stored on Bubble's server and never exposed to the client.
Some providers issue an API key that's used in place of the username or password. Check the provider's documentation to see how their credentials are formatted.
Oauth2 Password Flow
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.
How it works
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:
The client sends the username, password, and app credentials to the provider's token endpoint.
The provider validates the credentials and returns an access token.
The client includes the access token with each subsequent API call.
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.
When you'll encounter it
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.
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.
Setting it up in the API Connector
To configure OAuth2 Password Flow, select OAuth2 Password Flow from the Authentication dropdown in the collection's settings. The following fields will appear:
Username
The username used to authenticate against the provider's token endpoint.
Password
The password used to authenticate against the provider's token endpoint.
Token endpoint (POST)
The URL the API Connector sends the credentials to in order to receive an access token. The request is sent as a POST.
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.
Oauth2 Custom Token
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.
How it works
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.
When you'll encounter it
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.
Setting it up in the API Connector
To configure OAuth2 Custom Token, select OAuth2 Custom Token from the Authentication dropdown in the collection's settings. The following fields will appear:
Token endpoint (POST)
The URL the API Connector sends the token request to. The request is sent as a POST.
Token call headers
Custom headers to include with the token request. Click Add header to add a key and value pair.
Body
The body of the token request, formatted as a JSON object. Use <> to insert dynamic values.
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.
Oauth2 User-Agent Flow
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.
How it works
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:
The user clicks a button in your app to connect their account with the external service.
They're redirected to the provider's login page.
After signing in, they're shown a permissions screen describing what your app is asking to do.
If they approve, the provider redirects them back to your app with an access token.
Your app stores the token and uses it to make calls on the user's behalf.
When you'll encounter it
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.
Setting it up in the API Connector
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:
App ID
The client identifier issued by the provider for your live environment.
App Secret
The client secret issued by the provider for your live environment.
Dev. App ID
An optional client identifier used in your development environment, if the provider issues separate credentials.
Dev. secret
An optional client secret used in your development environment.
Scope
The permissions your app is requesting, as defined by the provider. Multiple scopes are typically separated by spaces or commas, depending on the provider's documentation.
Authentication goes in the header
When checked, the authentication credentials are sent in the request header instead of in the body. Check the provider's documentation for the expected format.
Token name
The name of the field in the provider's response that contains the access token. Defaults to access_token, which works for most providers.
Token is returned as querystring
When checked, indicates that the provider returns the access token in the URL query string rather than the response body.
Requesting an access token uses Basic Auth
When checked, the API Connector uses Basic Authentication when requesting the access token.
Add access_type=offline (Google APIs)
When checked, adds the access_type=offline parameter to the request. This is specific to Google APIs and is used to receive a refresh token alongside the access token.
Use a generic redirect URL
When checked, uses a generic redirect URL for the OAuth flow instead of an app-specific one.
Login dialog redirect
The URL the user is redirected to in order to log in and approve permissions. Use square brackets to insert dynamic parameters, such as [client_id].
Access token endpoint
The URL the API Connector uses to exchange the authorization response for an access token.
User profile endpoint
The URL used to retrieve the user's profile information after authentication.
User ID key path
The key in the user profile response that contains the user's unique identifier. Defaults to id.
User email key path
The key in the user profile response that contains the user's email address. Defaults to email.
The exact values for each field come from the provider's documentation, typically as part of registering your app with the service.
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:
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
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:
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.
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:
Set up a login workflow in your app that triggers the OAuth flow.
Preview your app with
debug_mode=truein the URL.Run the login workflow and complete the authentication with the provider.
Once the access token is received, the connection is marked as valid and calls can be set up against it.
JSON Web Token (JWT)
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:
The header, which describes the type of token and the signing algorithm used.
The payload, which contains the claims, such as the user's identifier, the issuer, and the expiration time.
The signature, which is generated using a secret key and used to verify that the token hasn't been tampered with.
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.
When you'll encounter it
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.
JWT formatting
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:
Setting it up in the API Connector
To configure JWT authentication, select JSON Web Token from the Authentication dropdown in the collection's settings. The following fields will appear:
Scope. The scope of access being requested, as defined by the provider. This tells the API what your app is asking permission to do.
Iss (account email). The issuer of the token, typically the email address of the service account associated with the credentials.
Access token endpoint. The URL the API Connector uses to exchange the JWT for an access token. This is provided by the API service.
Private key. The RSA private key used to sign the token. Paste the full key, including the
-----BEGIN RSA PRIVATE KEY-----and-----END RSA PRIVATE KEY-----lines. Below is a random example, but note that real RSA private keys can be longer:
Things to keep in mind
The space between
Bearerand the token is required. Without it, the provider won't be able to parse the header correctly.JWTs are case-sensitive. Copy the token exactly as the provider issues it.
Most JWTs have an expiration time built into the token's payload. Once expired, the token will no longer be accepted, and you'll need to generate a new one.
Always check the provider's documentation for the exact header format. Some providers use a different scheme, such as
TokenorJWTinstead ofBearer.
Client-side SSL certificate
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.
How it works
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.
When you'll encounter it
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.
Setting it up in the API Connector
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:
Certificate file content. The contents of the SSL certificate file issued by the provider. Paste the full certificate, including the
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----lines.Key file content. The contents of the private key file that pairs with the certificate. Paste the full key, including its header and footer lines, such as
-----BEGIN PRIVATE KEY-----and-----END PRIVATE KEY-----.
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.
FAQ: API Connector authentication
Last updated
Was this helpful?