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
  • Vulnerability Disclosure Policy
  • 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
  • Authentication
  • No authentication
  • Private key in URL
  • Private key in header
  • HTTP Basic Auth
  • Oauth2 Password Flow
  • Oauth2 Custom Token
  • Oauth2 User-Agent Flow
  • JSON Web Token
  • Shared Headers
  • Defining the call endpoint
  • JSON
  • XML
  • Image
  • Text, Number
  • Date Range, Number Range

Was this helpful?

  1. Account & Marketplace
  2. Building Plugins

Adding API Connections

Last updated 1 year ago

Was this helpful?

System hard limits

When creating plugins for Bubble, it's important to be mindful of the Bubble's hard system limits. These constraints for plugin development mirror those present in general Bubble development. The article below covers this subject:

Article:

API calls are a way to get data from external services or trigger some actions on the service's end (send a message, charge a card, etc.). Usually (but not always), the first type of calls are going to be GET requests, while the second one is a POST. A call usually requires some authentication, so that the service identifies who is calling it (and may charge per call, etc.). You add such calls in the API Tab of the Plugin Editor. This is where you will define how the calls are authenticated, and which calls are used as data sources or as actions.

Note: If an API call takes longer than 150 seconds to complete, Bubble will automatically retry this call. This is relevant if you're handling actions like sending emails where it may take more than 150 seconds to receive confirmation back from the service that the action has been completed. This may result in additional emails being sent if confirmation has not been processed.

You can see an example of the implementation of call of the iTunes API .

Implementing API connections can be different based on the API. While most APIs follow a few standards, if you hit some issues, we recommend reaching out to the API provider, and asking for help on the forum.

Authentication

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.

No authentication

Nothing is added to call, or you are handling authentication with custom parameters and handlers. Note that we do not recommend handling authentication yourself, and instead use Bubble's built-in authentication system for a more secure connection.

Private key in URL

A key is added in the URL, the key name can be modified in the editor.

Private key in header

A key is added in the headers of all requests. It is very similar to the previous option. Very often, the header will look like Authorization: KEY, but you can customize the name Authorization if needed.

HTTP Basic Auth

Oauth2 Password Flow

Oauth2 Custom Token

This flow is similar to the Password flow, but lets you define the call that returns the token yourself, in case it's not following the standard approach covered 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

This flow is the way most services connect when you use the API on behalf of the user (Facebook, Pinterest, Google, etc.). It will let you have access to users data when using the API (such as a profile name for Facebook). Setting such a service up will involve a few steps, as you will need to authenticate with your own account to be able to make authenticated calls in edit mode and initialize calls.

You usually start by setting an 'app' with the service you want to authenticate with. This service will then provide after this is set up a Client ID and a Secret that your app will use to communicate with the service.

You first need to fill the few pieces information and endpoints that are needed to get the token and the user ID. This endpoint will be used to generate the token, and retrieve the identity of a user with the service. All this information will be found in the API documentation. When you look at such documentation, we recommend looking for the section without SDK, but the web/HTTP section of it).

  • Scope: each Oauth2 provider will require you to enter a scope, that defines the level of permissions you are asking for from your users. It can be readonly, write, send-messages...

  • Login Dialog redirect: this the URL that will take the user to the service to authorize your app (and maybe login first to the service). It often will look like https://www.facebook.com/v2.8/dialog/oauth

  • Access token endpoint is the URL that is used server side to get from a temporary code to an access token. For Facebook, is is https://graph.facebook.com/v2.8/oauth/access_token.

  • User profile endpoint is the URL you use, once authenticated, to retrieve the current user's profile. This will include an ID, and usually an email (except if the service doesn't provide the email via the API). For Facebook, such URL is https://graph.facebook.com/v2.7/me (the 'me' is a common pattern).. In some cases, if the ID isn't returned at the top level of the response to the previous URL, or has a different key than 'id', you can overwrite this in the two settings under the endpoint box.

Here is what authentication for Spotify looks like:

In the case of Oauth2 User-Agent Flow, you'll need to authenticate yourself with your own personal account to be able to initialize the calls. A button will prompt you to go through the flow, and will save the token once you have gone through the process. Here again, your personal identity and credentials with the service will not be shared with users that use your plugin.

JSON Web Token

-----BEGIN RSA PRIVATE KEY-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
................................................................
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END RSA PRIVATE KEY-----

Shared Headers

If you need to add some shared headers to all calls, including the authenticating ones, you can define them in the following section. Note that the value you will set here can be 'hidden' or 'secret'. Hidden settings will be hardcoded by you, as the plugin builder, and plugin users will not fill this key. Most of the time, this is used for technical headers, like a content-type, etc. The secret type will prompt your plugin users to enter a key in the Plugins Tab.

Defining the call endpoint

Once you have properly entered authentication information, you can start setting up your calls. You start by defining the request method, copy the endpoint that should be hit, and define the different parameters that the user will have to fill. Note that if you enter a part of the URL between [ and ], the value in between will be a parameter.

Parameters can be of several types: public, hidden or secret.

  • Public parameters will be modified by the user at the call level (that's for instance a term for query API call).

  • Hidden parameters are for the plugin builder, and won't be exposed to the user that uses the plugin. For instance, it can be an encoding type, etc.

  • Secret parameters are good for keys, etc. Users will enter these in the Plugins Tab of the editor.

Once a call is defined you need to initialize it to make it usable in Bubble. An API call can return five different types of data.

JSON

This is the most typical case of a REST API, it returns an object with key and values. If you pick this type, you will be prompted to pick a data type of each key in a popup after initializing the call. When you initialize a call, Bubble makes the actual request, and analyze the returned data.

XML

Some APIs returns their response as XML. Often, this can be converted into a JSON object. If you are dealing with such an API, you can use XML and get data as a JSON object, and go through the flow described above. Note that not all XML responses can be converted as JSON. If Bubble fails to do so, an error message will be displayed.

Image

Some APIs return the raw image as the response. It can be a URL that you can use in an <img> tag, for instance. In such a case, the API call in Bubble will return an image that can be used in an Image element, or as a page background.

Text, Number

If the API returns a string or a number (without structuring this as a JSON object), you should pick this option.

Note that changing the types once an API is public can be non-backward compatible, so do this with caution and make sure to document this as a breaking change when you publish your plugin (see below).

Date Range, Number Range

A username/password will be sent with each request, according to the HTTP Basic Auth protocol (see ).

A password and a user name is used to get a token (see for general information about this flow), that can expire and that is renewed automatically by your app. The token is returned when calling an endpoint that you'll need to fill in the Editor. The endpoint can be found in the API documentation. Search for 'token' or 'OAuth Bearer token' in the documentation.

Some services use this more advanced to handle scope and permissions. This is usually for enterprise-type services, like Box or Google Cloud. To authenticate with such a service, you will need to enter the scope, the email that is used to set up the service account and the endpoint that returns the token. You will also need to enter the private RSA key that the service is providing to set up the connection. Note that the key should be formatted as, including the '-----BEGIN RSA PRIVATE KEY-----' and '-----END RSA PRIVATE KEY-----'.

While these are Bubble data types, we do not support these data types for our API Connector. If you want to use the API Connector for date ranges or number ranges, a workaround is either to send dates/numbers as two separate fields or as a two-item list of dates/numbers and format them as ranges elsewhere in your app. If you want to use the API Connector to query range data from another Bubble app, we suggest using the instead.

this
this
protocol
App Connector
Hard limits
here