Bubble's API Connector supports multiple authentication methods for connecting to external APIs. This tutorial covers configuring API key authentication in headers, Bearer token setup, OAuth2 user-agent flow for services like Google and GitHub, HTTP Basic Auth, and best practices for keeping credentials secure using private parameters and Bubble's server-side routing.
Overview: API Authentication in Bubble
This tutorial covers every authentication method available in Bubble's API Connector. You will learn when to use each method and how to configure them securely for connecting to any external REST API.
Prerequisites
- A Bubble app on any plan
- The API Connector plugin installed
- API credentials from the service you want to connect to
- Basic understanding of HTTP requests and headers
Step-by-step guide
Set up API key authentication in headers
Set up API key authentication in headers
Open the API Connector plugin. Add a new API and give it a name. For authentication, select 'Private key in header'. Enter the header name your API expects (commonly 'X-API-Key', 'api-key', or 'Authorization') and paste your API key as the value. Check the 'Private' checkbox to ensure the key is never sent to the browser. This is the most common authentication method for services like OpenAI, SendGrid, and weather APIs. The API Connector routes all requests through Bubble's server, keeping your key hidden from end users.
Pro tip: Always check the 'Private' checkbox on any parameter containing an API key or secret. This ensures the value stays on Bubble's server.
Expected result: API calls include your API key in the header, authenticated server-side through Bubble.
Configure Bearer token authentication
Configure Bearer token authentication
For APIs requiring Bearer tokens (JWT-based auth like Firebase, Supabase, or your own backend), select 'Private key in header' and set the header name to 'Authorization' with the value 'Bearer YOUR_TOKEN_HERE'. If the token is static, paste it directly. If the token is dynamic (refreshed periodically), store the current token in a Data Type and reference it dynamically in your API call. For services that issue short-lived tokens, create a backend workflow that refreshes the token before it expires and updates the stored value.
Expected result: API calls include a Bearer token in the Authorization header for services requiring JWT authentication.
Set up OAuth2 user-agent flow
Set up OAuth2 user-agent flow
For APIs requiring user authorization (Google, GitHub, Facebook, Spotify), select 'OAuth2 User-Agent Flow' as the authentication type. Fill in: App ID (client ID from the API provider), App Secret (client secret), Scope (permissions requested, like 'email profile'), Authorization URL (the provider's auth endpoint), and Access Token URL (the token exchange endpoint). After saving, Bubble provides a redirect URL — add this to your API provider's allowed redirect URLs. When a user initiates the flow, Bubble handles the authorization redirect and token exchange automatically.
Expected result: Users can authenticate with third-party services via OAuth2 with automatic token management.
Configure HTTP Basic Auth
Configure HTTP Basic Auth
For APIs using HTTP Basic Auth (common with older APIs and some payment gateways), select 'HTTP Basic Auth' as the authentication type. Enter your username and password. Bubble encodes these as a Base64 string in the Authorization header automatically. The credentials are kept server-side and never exposed to the browser. Some APIs use the API key as the username with an empty password, or vice versa — check your API documentation for the correct approach.
Expected result: API calls include properly formatted Basic Auth headers with credentials kept server-side.
Secure your API credentials
Secure your API credentials
Review all your API Connector configurations for security. Ensure every sensitive parameter has the 'Private' checkbox checked. Never use 'Client safe' for any credential or token. Verify that API keys are not hardcoded in HTML elements or JavaScript plugins. For OAuth2, store refresh tokens securely in the User Data Type and never log them. Regularly rotate API keys following your provider's recommended schedule. If you suspect a key has been compromised, revoke it immediately in the provider's dashboard and generate a new one.
Expected result: All API credentials are properly secured with private parameters and no browser exposure.
Complete working example
1{2 "AUTHENTICATION_METHODS": {3 "API_KEY_IN_HEADER": {4 "auth_type": "Private key in header",5 "header_name": "X-API-Key",6 "header_value": "sk_your_api_key_here",7 "private": true,8 "use_case": "OpenAI, SendGrid, weather APIs"9 },10 "BEARER_TOKEN": {11 "auth_type": "Private key in header",12 "header_name": "Authorization",13 "header_value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",14 "private": true,15 "use_case": "Firebase, Supabase, custom backends"16 },17 "OAUTH2": {18 "auth_type": "OAuth2 User-Agent Flow",19 "app_id": "your_client_id",20 "app_secret": "your_client_secret",21 "scope": "email profile",22 "auth_url": "https://provider.com/oauth/authorize",23 "token_url": "https://provider.com/oauth/token",24 "use_case": "Google, GitHub, Facebook, Spotify"25 },26 "BASIC_AUTH": {27 "auth_type": "HTTP Basic Auth",28 "username": "api_key_or_username",29 "password": "api_secret_or_password",30 "use_case": "Legacy APIs, some payment gateways"31 }32 },33 "SECURITY_CHECKLIST": [34 "All sensitive params marked Private",35 "No credentials in Client safe params",36 "No keys in HTML or JS elements",37 "OAuth tokens stored securely",38 "Keys rotated on schedule",39 "Compromised keys revoked immediately"40 ]41}Common mistakes when handling API Call Authentication in Bubble
Why it's a problem: Not checking the Private checkbox on API key parameters
How to avoid: Always check Private for any parameter containing credentials, keys, or tokens
Why it's a problem: Hardcoding API keys in HTML elements or JavaScript plugins
How to avoid: Keep all API credentials in the API Connector with Private parameters. Never put keys in frontend code.
Why it's a problem: Using Client safe for credential parameters
How to avoid: Use Private for credentials. Client safe is only for non-sensitive dynamic values like search queries.
Best practices
- Always use Private parameters for any sensitive values
- Route all API calls through Bubble's server (default) to hide credentials
- Store OAuth refresh tokens securely in the User Data Type
- Rotate API keys on a regular schedule
- Test API authentication in development before deploying to live
- Document which authentication method each API connection uses
- Revoke compromised keys immediately and generate replacements
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to connect my Bubble.io app to an API that requires Bearer token authentication. How do I set this up in the API Connector and keep the token secure?
Help me configure the API Connector to connect to the Google Calendar API using OAuth2. I need users to authorize access to their calendars.
Frequently asked questions
Is it safe to store API keys in Bubble?
Yes, when using the Private parameter setting. Bubble routes API calls through its servers and never exposes Private parameters to the browser. Bubble's infrastructure is SOC 2 compliant.
What is the difference between Private and Client safe?
Private parameters stay on Bubble's server and are never sent to the browser. Client safe parameters are sent to the browser for dynamic assignment but should never be used for sensitive data.
How do I refresh an expired OAuth2 token?
Bubble handles OAuth2 token refresh automatically for the User-Agent flow. For custom OAuth implementations, create a backend workflow that uses the refresh token to request a new access token before the current one expires.
Can I use different API keys for development and production?
Yes. Set up two API configurations in the API Connector or use different key values. Many API providers offer separate test and production keys.
What if the API uses a custom authentication scheme?
Use 'None/Self-handled' authentication and add your custom auth headers or parameters manually in the call configuration.
Can RapidDev help configure API authentication?
Yes. RapidDev can set up secure API integrations including OAuth2 flows, token refresh mechanisms, and multi-provider authentication for your Bubble application.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation