Bubble Docs
  • Introduction
  • New? Start Here
  • What is Bubble?
  • The Glossary
  • User manual
    • Getting started
      • What is Bubble?
      • Building your first app
        • Planning features
        • Database structure
        • Design and UX
        • eCommerce and payments
          • Shopping cart
          • Checkout page
          • One-time payments
          • Subscriptions
          • Marketplace
      • Creating and managing apps
      • The Bubble editor
        • Tabs and sections
          • Design tab
            • The element tree
            • The property editor
          • Workflow tab
          • Data tab
          • Styles tab
          • Plugins tab
          • Settings tab
            • Application settings
              • Custom headers/body
              • Visual settings
              • Social media sharing
              • Translating your app
              • Email settings
              • Collaboration
            • Custom domain and DNS
          • Logs tab
        • Tools
          • Key features
          • The search tool
          • The Issue Checker
          • The element tree
          • The element property editor
          • The debugger
          • Notes
        • Previewing your app
      • Transitioning to Bubble from...
        • JavaScript
        • HTML and CSS
        • SQL
    • Design
      • Elements
        • The element hierarchy
          • The element tree
        • The page
        • Containers
          • Groups
          • Repeating groups
          • Table elements
          • Popups
          • Floating groups
          • Group focus
        • Visual elements
        • Input forms
          • Text and numbers
          • Dates and time
          • File uploads
          • Selection controls
        • Reusable Elements
      • Styling
        • Color variables
        • Font variables
        • Styles
        • Custom Fonts
      • Responsive design
        • Building responsive pages
        • Legacy articles
          • The Basics (Legacy)
          • Building Responsive Pages (Legacy)
          • Migrating Legacy Pages
          • Tips When Designing (Legacy)
      • Templates
      • The Component Library
      • Importing from Figma
    • Data
      • The database
        • Data types and fields
        • Creating, saving and deleting data
        • Finding data
        • Displaying data
        • Protecting data with privacy rules
        • The database editor
        • Export/import data
          • Exporting data
          • Importing data (CSV)
        • Working with location data
        • Using Algolia
        • Database structure by app type
          • Marketplace Apps
          • Directory & Listings Apps
          • Social Network Apps
          • SaaS Apps
          • Project Management Apps
          • CRM Apps
          • Professional Services Apps
          • On-demand Apps
          • Documentation/ CMS Apps
          • Applicant Tracking System (ATS) Apps
          • Portfolio Apps
          • Gallery Apps
          • Online Store / Ecommerce Apps
          • Blog Apps
          • Messaging App
          • Dashboards
          • Building Block Apps
          • Bubble as a backend
      • Files
      • Images
      • Static data
        • App texts (translations)
        • Option sets
      • Temporary data
        • Custom states
        • URL parameters
      • User accounts
        • Authentication plugins
          • Facebook plugin
          • Fitbit plugin
          • Google plugin
          • Instagram plugin
          • LinkedIn plugin
          • Pinterest plugin
          • Slack plugin
          • Wistia plugin
          • YouTube plugin
        • Cookies set by Bubble
      • Time, dates and time zones
    • Logic
      • The frontend and backend
      • Workflows
        • Events
          • Frontend events
            • Recurring workflows
            • Custom events
          • Backend events
            • Database trigger events
        • Actions
        • API Workflows
      • Dynamic expressions
      • Conditions
      • Navigation
        • Single-page applications (SPA)
        • Multi-page applications
        • Page slugs
    • Workload
      • Understanding workload
        • Activity types
        • The workload calculation
        • Client-side and server-side processing
      • Tracking workload
        • Measuring
          • Using App Metrics
        • Monitoring
          • Workload notifications
          • Infinite recursion protection
      • Optimizing workload
        • Optimization framework
        • Optimization checklist
          • Page load
          • Searches
          • Workflows and actions
          • Backend workflows
        • Agency showcases
          • Minimum Studio
          • Neam
          • Support Dept
    • Security
      • Bubble's security features
      • Planning app security
      • Client-side and server-side
      • Bubble account security
      • App security
      • Page security
      • Database security
      • API security
        • API Connector security
        • Data API security
        • Workflow API security
      • Flusk
        • Overview
        • Flusk plan features
        • Getting started with Flusk
        • Flusk security tools
          • The Issues Explorer
          • Issue details
          • Tools and settings
            • Pages rating
            • Database rating
        • Flusk FAQ
      • Cookies
      • Security checklist
    • Publishing your app
      • Web app
      • Native mobile app
        • Global native mobile settings
        • iOS App Store
        • Google Play Store
        • Publishing FAQ
    • AI
      • Generate apps with AI
        • About AI app generation
      • AI page designer
      • Connect to AI agents
    • Maintenance
      • Collaborators
      • Version control
        • Best practices: Version control
        • Transitioning from the legacy version control
        • Terminology: Version control
        • Version Control (legacy)
      • Commenting
      • Database maintenance
        • Copying the database
        • Restoring database backups
        • Bulk operations
          • Bulk operation methods compared
        • Wiping change history
      • Performance
        • Hard limits
        • Capacity Usage (legacy)
        • Notes on queries
      • SEO
        • Introduction to SEO
        • SEO: App
        • SEO: Page
      • Testing and debugging
        • Introduction to testing and debugging
        • The debugger
        • The server logs
        • Supported browsers
      • API workflow scheduler
    • Integrations
      • API
        • Introduction to APIs
          • What is a RESTful API?
        • The Bubble API
          • Bubble API terminology
          • Authentication
            • How to authenticate
            • No authentication
            • As a User
            • As an admin
          • The Data API
            • Data API Privacy Rules
            • Data API endpoints
            • Data API requests
          • The Workflow API
            • Workflow API privacy rules
            • Workflow API endpoints
            • API workflows
              • Creating API workflows
              • Scheduling API workflows
              • Recursive API workflows
              • API Workflow Scheduler
              • Case: Stripe notifications
        • The API Connector
          • Authentication
          • API Connector security
          • API guides
            • OpenAI
              • Authentication
              • Calls
                • ChatGPT
                  • Chat
            • Google Translate
              • How to setup Google API keys
          • Streaming API
        • API security
        • Plugins that connect to APIs
        • API Glossary
      • Plugins
        • What Plugins Can Do
        • Installing and using Plugins
        • Authentication plugins
        • Special Plugins
      • SQL Database Connector
      • Bubble App Connector
      • WorkOS
        • WorkOS SSO
        • WorkOS API
    • Infrastructure
      • Sub-apps
      • Bubble release tiers
      • Hosting and scaling
        • How Bubble hosting works
        • Scaling with Bubble
        • CDN (Cloudflare)
        • Bubble app names
        • Domain and DNS
      • Compliance
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks and standards
    • Bubble for Enterprise
      • Hosting and infrastructure
        • Dedicated instance
          • The Dedicated editor experience
          • Technical specs
          • Main cluster dependencies
          • Customizable options
          • Migration process
            • Pre-migration
            • During migration
            • Post-migration
      • Security and compliance
        • Single sign-on (SSO)
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks
        • Bubble's security features
      • Admin and collaboration
      • Priority support
      • Billing and Payment Guideline for Dedicated Instances
  • Core Reference
    • Using the core reference
    • Bubble's Interface
      • Design tab
      • Design tab (Legacy)
      • Workflow tab
      • Data tab
      • Styles tab
      • Styles tab (Legacy)
      • Plugins tab
      • Settings tab
      • Logs tab
      • Template tab
      • Toolbar
      • Top and context menu options
      • Deployment and version control
        • Deployment & Version Control Dropdown (legacy)
      • Notes
    • Elements
      • General properties
      • General properties (Legacy)
      • Styling properties
      • Styling Properties (Legacy)
      • Responsive Properties
      • Responsive Properties (Legacy)
      • Conditional formatting
      • States
      • Page Element
        • Page Element (Legacy)
      • Visual Elements
      • Containers
      • Container Layout Types
      • Containers (Legacy)
      • Input Forms
      • Reusable Elements
      • Element Templates (legacy)
    • Workflows
    • Events
      • General events
      • Element events
      • Custom events
      • Recurring event
      • Database trigger event
    • Actions
      • Account
      • Navigation
      • Data (things)
      • Email
      • Element
      • Custom
    • Data
      • Data Sources
      • Operators and comparisons
      • Search
      • Privacy
    • Styles
    • API
      • The Bubble API
        • The Data API
          • Authentication
          • Data API endpoints
          • Data API requests
        • The Workflow API
      • The API Connector
        • Authentication
        • Adding calls
    • Bubble-made Plugins
      • AddtoAny Share Buttons
      • Airtable
      • API Connector
      • Blockspring
      • Box
      • Braintree
      • Bubble App Connector
      • Chart.js
      • Circle Music Player
      • Draggable Elements
      • Dropzone
      • Facebook
      • Fitbit
      • Full Calendar
      • Google
      • Google Analytics
      • Google Optimize
      • Google Places
      • Ionic Elements
      • iTunes
      • Slidebar Menu
      • LinkedIn
      • Localize Translation
      • Mixpanel
      • Mouse & Keyboard Interactions
      • Multiselect Dropdown
      • Progress Bar
      • Rich Text Editor
      • Rich Text Editor (Legacy)
      • Screenshotlayer
      • SelectPDF
      • Slack
      • Segment
      • Slick Slideshow
      • SQL Database Connector
      • Star Rating
      • Stripe
      • Tinder-like Element
      • Twitter
      • YouTube
      • Zapier
    • Application Settings
      • App plan
      • General
      • Domain / email
      • Languages
      • SEO / metatags
      • API
      • Collaboration
      • Sub-apps
      • Versions
  • Account & Marketplace
    • Account and billing
      • Pricing and plans
        • Plans and billing
        • Billing cycle
        • FAQ: Pricing and Workload
      • Account Management
      • Building Apps for Others
      • Selling on the Marketplace
      • Plans & Billing (legacy)
    • Official Bubble Certification
      • Hiring certified developers
    • Building Plugins
      • The Plugin Editor
      • General Settings
      • Updating to Plugin API v4
      • Adding API Connections
      • Building Elements
      • Building Actions
      • Loading Data
      • Publishing and versioning
      • Github Integration
    • Building Templates
    • Application and data ownership
    • Marketplace policies
    • Bug reports
  • Beta features
    • About the Beta features section
    • Native mobile apps 🔒
      • Introduction
        • What is a native mobile app?
        • Native mobile vs. web development
        • Differences in native and web elements
        • Native mobile app terminology
      • Building
        • Views and navigation
        • Native mobile actions
        • Components and gestures
        • Device resources
          • Location services
          • Camera/photo library
      • Previewing
      • Publishing
Powered by GitBook
On this page
  • The API Connector
  • Installing the API Connector
  • External API documentation
  • Test accounts
  • Naming API providers
  • Authentication
  • Authentication methods
  • API tokens and security
  • Shared headers
  • Shared parameters
  • Adding calls
  • Use as
  • The HTTP method
  • The URL and endpoint
  • Initializing a call
  • Raw body text

Was this helpful?

  1. User manual
  2. Integrations
  3. API

The API Connector

This section covers Bubble's API Connector. The API Connector is used to make outbound connections to external applications and use it as a data source or trigger actions.

Last updated 29 days ago

Was this helpful?

In the we covered API requests that are incoming – they are initiated by an outside system and Bubble takes some kind of action based on their credentials, endpoint and parameters.

This is our in-depth manual article on the API Connector. If you are familiar with APIs and want the shorter technical reference go to the . We also have a dedicated article covering .

In this section we’ll look at requests that are outbound – when your Bubble app sends a request to an external system. When you use the API Connector, your Bubble app is the client and the API service is the server.

You can read more about the client/server relationship in our . Article section:

By pointing the API Connector to different URLs (Universal Resource Locator) you can access specific that the API provider offers.

Just like incoming requests these calls can ask for some data to be returned or for an action to be performed.

Structurally, you’ll recognize what they look like: they also use an that includes a like GET, POST, PATCH and DELETE.

The API Connector

The API Connector is a special plugin built by Bubble's development team that lets you connect to any service that exposes a , . You can use this to add API calls to fetch data from an external service, or post data to trigger some actions on the service's end.

Installing the API Connector

The API Connector is a plugin created by Bubble and needs to be installed in your application before it can be used.

To install the plugin:

  1. Navigate to the Plugins section of the Bubble editor and click Add plugin.

  2. Search for API Connector

  3. Click the Install button

External API documentation

Every API service is different and to make it possible to connect successfully to their platform, most providers offer API documentation. Using the external documentation is critical to understand how to authenticate and make calls to that specific service, so we recommend you get to know it before you start.

If this is your first time working with APIs, the documentation may seem fairly technical at first, but you’ll find that with the RESTful API style most providers follow a similar standard.

Most APIs will go through three steps before they can be used:

  1. First set up the for the API service

  2. Secondly we set up the different (s) we want to use

  3. Then we the call to make sure it works and to see the server's response

Test accounts

Many API providers such as Stripe offer a demo account that you can use to test your API calls without making any actual changes (or payments in the case of Stripe). Check whether the service you want to connect to offers this kind of testing environment to be able to properly test all your calls with no risk.

Naming API providers

The first part of setting up a new API request is to give the service a name. This will typically be a descriptive name (often the same as the provider’s name) such as Stripe, Google Cloud and OpenWeatherAPI.

The name is used around the Bubble editor to organize the different calls that we’ll add later. It’s therefore a good idea to use a name that makes the relevant call easy to find later.

The API name becomes part of your application’s client-side code and should not contain any sensitive information.

Authentication

As we covered in our general guide on how APIs work, many API services will require . This is the process of identifying who the client is in order to determine what resources it should have access to.

Authentication methods

There are many different ways to authenticate. Most API providers will have documentation available online that specifies their authentication method and many require you to generate a unique API token.

Method
Description

None or self-handled

Private key in URL

The private key is included as a parameter in the URL.

Private key in header

The private key is included as an HTTP header in the request.

HTTP Basic Auth

The client sends username and password in plain text.

OAuth2 Password Flow

The client sends username and password and receives an access token in return.

OAuth2 User-Agent Flow

OAuth2 Custom Token

The client sends a custom token to the server for verification.

JSON Web Token (JWT)

The client sends a JSON web token to the server for verification.

Client-side SSL certificate

The client presents a SSL certificate to the server for verification.

⚠️ Privacy considerations when using the API Connector as data

Scenario

  • None or self-handled

  • OAuth2 User-Agent Flow

…and the API relies on private keys or other sensitive parameters passed as query strings or body parameters.

Behavior to be aware of:

In these configurations, Bubble does not enforce privacy rules or validate these requests against the current database state. As a result, sensitive data may be exposed or become accessible to users who should not have access. We suggest the configuration below to ensure stronger control over access.

Recommended solution: To mitigate this risk, do not only pass private keys as parameters. Instead, use the Private key in header authentication method in the API Connector. This ensures:

  • The key is securely stored and only sent from the server.

  • Bubble’s server-side logic handles the call and can enforce privacy rules.

API tokens and security

We recommend learning how to set up the API Connector in a secure way. If you want to learn more about this, check out our dedicated article on API Connector security.

If you are new to APIs it’s important to emphasize here the importance of keeping your API token secret. API tokens in principle serve the same function as a username and password, but they add security and flexibility that is useful to an API provider:

  1. They can be easily generated and revoked: Unlike a username and password, which are typically created and managed by an actual person, API tokens can be easily generated and revoked by the API provider. This makes it easy to control access to the API and limit the impact of any security breaches.

  2. They are more secure: API tokens are generally more secure than username and password combinations, because they are typically harder to guess or brute force. They can also be rotated regularly to further improve security.

  3. They are more convenient: API tokens are generally easier for developers to work with than username and password combinations, because they do not require any special handling. This can make it easier for developers to use your API and can increase adoption of your API.

Just like a username and password, a token is only as secure as the one who manages it. Tokens to important services like Stripe should be handled with the utmost confidentiality.

API keys/tokens should never be stored in Option Sets or in on-page elements and/or workflows, since that makes them visible in your application’s client-side source code.

Shared headers

Sometimes you'll need to add the same header to all your calls. This can be related to authentication, but it doesn't have to be. Another typical key and value included in the header section is the content-type, which specifies the expected format of the call.

Consult the external API documentation to see if they require any specific headers.

Shared parameters

Shared parameters, like the headers described above, will be added to each and every call in the relevant API. Shared parameters are added to the body of the request rather than the header.

It doesn't make any technical difference whether you add headers and parameters directly to each call or use the Shared headers/parameters feature. Adding them to this section will simply save you some time and make the headers and parameters easier to set up and manage.

Adding calls

Now that we have 1) given our API service a descriptive name and 2) authenticated as a client (if necessary) it’s time to add the actual calls.

Again we need to name the call before doing anything else. Give it a descriptive name that can be combined with the name you gave earlier to the API provider. For example, you might name the API Provider Stripe and the API Call Create payment.

Secondly, we need to tell Bubble what this call will be used for in the Use as dropdown.

Use as

The Use as dropdown lets you select whether to use that particular API call as a data source or an action:

Data

Use as data means that Bubble will treat the API call as a data source. Use this for calls that you set up to retrieve data that you want to display in your app. You will find API data sources in the Get data from external API in the dropdown list of data sources.

Action

Use as action makes the API call available as an action in your Workflow editor. You will find API action calls in the workflow editor under Plugins.

The HTTP method

When a call is made to a specific , we need to specify an that tells the server what kind of action we want to initiate. The five most used HTTP methods are:

Action

Description

GET

Retrieve data

POST

Create data

PUT

Update data

PATCH

Replace data

DELETE

Delete data

HTTP methods are sometimes called HTTP verbs. Generally they are used as illustrated in the table above, but to find the correct HTTP method for the resource you want to access, check the API providers documentation.

The URL and endpoint

For example, when we were looking at Bubble’s (used to give external systems access to the database) and (used to give external systems access to workflows) we looked at how Bubble generates a unique URL for each data type you choose to expose in the Data API and each API Workflow you choose to expose in the backend workflow editor.

External RESTful APIs work in the same way: you direct your Bubble application to a specific URL in order to reach the resource that you want. Together, the HTTP method and the endpoint form a unique API endpoint that defines the specific action that is being requested.

For example, a GET request to a "/users" endpoint might be used to retrieve a list of users from an API, while a POST request to the "/users" endpoint might be used to create a new user.

Finding the correct endpoint

The endpoint is the combination of the HTTP method and the URL (resource locator). What method to use and what the URL is differs between different API services, and you can usually find the correct endpoint by consulting the documentation of the API provider.

Initializing a call

When you initialize a call, keep in mind that Bubble sends an actual call to the server, potentially loading and manipulating data.

The test data that you enter in the value field of a parameter, is visible in your app's code unless the Private box is ticked. You should remove any sensitive data from this field before you deploy.

When a call is set up, it needs to be initialized. This means to run the call to test it. This is a required step before the call can be used in your app, for a few reasons:

  • It informs us about the success or failure of the call.

  • It furnishes us with a response that outlines the JSON data format. This enables Bubble to establish the call as a data source, as it understands its organization.

    • You can also have a look at the data (structured or raw) that the server returns, to verify that it gives the expected results, and to understand its structure

When you click the Initialize a call button, Bubble sends the call to the server, and displays the response in a popup. If the call is unsuccessful, the API Connector will show you the relevant error message.

Raw body text

Raw body text is an experimental feature. Currently, it is only accessible via the API connector when the include errors or include headers checkbox is clicked.

Also, it is not available if you use a nested field in a dynamic expressions, such as first items's raw body text.

You can also view the raw body text returned by the server. This refers to the unprocessed information received from the API endpoint.

Raw data provides the foundational information that can then be parsed, manipulated, or displayed as needed within your app. It forms the basis for further processing and integration within the app's actions and data sources.

Case: Setting up Google Translate in the API Connector

Plugins: Bubble's plugin store offers thousands of plugins both made by Bubble and the community. Many plugins let you connect to well-known API services quickly and effortlessly without having to set it up in the API Connector. Link: Article:

The list below represents the most common authentication types. You can read more about each type in the article below: Article:

No authentication required. ⚠️ (see security note )

Similar to OAuth2 Password Flow, but for user-agents. ⚠️ (see security note )

When configuring API calls in the API Connector as Data (i.e. “Use as: Data” ) there is a potential security risk if the Authentication method is set to either:

Article:

In our we explored how a call uses a URL to identify a specific resource.

To have a closer look at how the API Connector works in practice, you can check out our guide on how to connect to Google Cloud to utilize the Cloud Translation API. Article:

Plugin store
Plugins that connect to APIs
Authenticating with the API Connector
API Connector security
general article on APIs
Case: Connecting to Google Translate with the API Connector
below
below
Bubble API section
API Connector reference entry
API Connector security
Introduction to APIs
Our long-form video course gives you an introduction to how APIs work and how to use the API Connector.
The client/server relationship
The API Connector handles calls that come from your Bubble app to another application.
Click the Install button to use the API Connector in your application.
Giving your API a descriptive name makes it easier to organize the different providers.
To add a call, click the Add another call button
Setting the API call to be of type Data allows you to use the call as a data source. That way you can use it to populate Repeating Group for example.
Setting an API call to type Action lets you run that call from a workflow in your application. The label (RentalSoftware - Create Unit) is a combination of the name you gave the API provider and the name of the call in the API Connector.
Setting the HTTP method in the dropdown in red tells the external app what kind of action you want to take. GET usually means you want to return data.
In the example above, we have found the correct endpoint to translate a text using the Google Cloud Translation API. The documentation also
API providers like Stripe offer detailed on how to set up API connections.
documentation