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
  • API Keys
  • API key security in the API Connector
  • Development keys and live keys
  • Authentication methods
  • None or self-handled
  • Private key in header
  • Private key in URL
  • HTTP Basic Auth
  • Oauth2 Password Flow
  • Oauth2 Custom Token
  • Oauth2 User-Agent Flow
  • JSON Web Token
  • Client-side SSL certificate

Was this helpful?

  1. User manual
  2. Integrations
  3. API
  4. The API Connector

Authentication

This section covers the different authentication methods the API Connector offers.

Last updated 1 month ago

Was this helpful?

Authentication is the process of identifying who a is in order to determine what they have access to on the server.

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 a 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 every client who makes a 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 Keys

Many APIs use what's called an API key. This is a securely generated token that serves as both a username and a password.

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 in the API Connector

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.

API calls from the API Connector are routed through Bubble's server, which means that all the authentication methods below offer the same level of added security. RESTful API calls are sent via the , which in modern web systems is encrypted with during .

Development keys and live keys

Many API providers allow you to generate to sets of keys: one for testing and one for the live version of your app (often called production).

It's best practice to use these keys as intended: 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.

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.

In this article we use multiple fairly technical terms to explain how the different authentication methods work. You may find our API Glossary useful if there are words or terms you're unfamiliar with. If you are new to API's you may also find our Introduction to APIs and What are RESTful APIs articles useful.

Authentication methods

There are many different ways to authenticate, and which method to use is specified by the API provider in their documentation. Below we will go over the different methods that Bubble supports, which cover most RESTful API providers.

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

None or self-handled

Some providers require no authentication. This can also be the case if you are connecting two systems that you both control. By selecting this option Bubble will not send any authentication with the call.

You can also handle authentication with custom parameters and handlers but this should be done with caution.

We do not recommend handling authentication yourself as this comes with a risk of exposing your API keys and the connection. Bubble's built-in authentication system is designed to keep your data and connections secure.

Private key in header

With this method, the key is added to the of all requests. Most providers name the parameter Authorization, but you can give the parameter a custom name as specified in the external API documentation if needed.

  1. The first is the name of the parameter the server expects. Check the external API documentation for this.

  2. The third is the API key for the live version of your app

  3. The second is the actual API key for the development version of your app

What does a private key in the header look like?

Authorization: Bearer <token>

The example above would be one row of the header – it also contains other data. The <token> is replaced by the actual token without the <> signs.

The actual key name in the example above can look different depending on the API provider. Consult their documentation to find the right formatting for their particular setup.

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 option lets you add the key in the URL of each call.

  1. The first field is the name of the key, which specifies how the authorization parameter key should be named in the URL. You will need to check the API provider's documentation for how they want the key to be named

  2. The second is the actual API key for the live version of your app

  3. The third is the API key for the development version of your app

What does a private key in the URL look like?

With this information, Bubble will add a parameter to the URL of each call, like the example below:

GET https://myapp.bubbleapps.io/version-test/api/1.1/obj/datatype/UID?private-key=this-is-the-live-key

In this example we are using the GET method to get information about a specific data type in a Bubble app..

HTTP Basic Auth

The HTTP Basic Auth method is a bit different than the two previous in that it works by sending the client's username and password in the header of the request. The username and password is often encoded using .

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

What does HTTP Basic auth look like in the header?

The HTTP Basic auth method looks a lot like the private key in header method:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The "dXNlcm5hbWU6cGFzc3dvcmQ=" string is an encoded version of the string "username:password".

Oauth2 Password Flow

In the Oauth2 Password Flow method you send a username and password to the external app, and the app authenticates using those credentials. The external server generates a token that can be used for subsequent requests until it expires or is revoked (at which point Bubble will renew it for you).

Your app needs to call a specific endpoint to get the returned token, and you need to consult the external documentation to determine what the URL of this endpoint is.

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

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.

Oauth2 Custom Token

This flow is similar to the Oauth2 Password Flow but offers more customization in case the API provider is not following the common standard in the method 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

Setting up the Oauth2 User-Agent Flow can be a bit complicated if you are not familiar with APIs. There are many plugins that can set up the connection for you without having to go through the API Connector. Article: Finding API-related plugins

The Oauth2 User-Agent Flow is the most widely used to to connect when you use the API on behalf of the User (meaning that the User is logging in using their own account to the third-party service, such as their Facebook or LinkedIn profile). This method takes a few more steps than the previous ones, as you will in practice need to authenticate with two accounts:

  1. First, you connect to the external app using credentials that the app has generated for you.

  2. Then, the User authenticates themselves with their own credentials on a page hosted by the external app and authorizes that your app is given access. Oftentimes they will already be logged in and simply need to authorize the request.

  3. The API Connector then makes a call to a specific endpoint to the newly generated token that provides access to subsequent calls

  4. Finally, the API Connector connects to another endpoint using the token to authenticate and getting access to the User's profile information (such as email, profile photo, etc). The information available depends on the service and sometimes the personal settings of the User in the third-party system.

Terms used in the external Oauth2 API documentation

When you check the external documentation for instructions on how to set up the Oauth2 User-Agent Flow with that provider, you'll often come across the following terminology:

  • Resource Owner: The resource owner refers to the User of your app. Since your app is asking for access to the resources belonging to that User specifically, it follows that they are described as the owner.

  • Resource or Authorization Server: this refers to the server that manages authorization and the server that hosts the resource. They can sometimes be the same, but not always.

  • Client: the client is the app that is requesting access to the resource: your Bubble app.

You'll find more API-related terms in our API Glossary.

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:

Scope example
Description

admin

Full administrative access to make changes to a User's resources

email

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:

readonly email

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

As we explored above, the Oauth2 User-Agent Flow involves first authenticating your app as the 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:

Key
Description

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.

JSON Web Token

Some services use this more advanced protocol to handle scope and permissions. This is usually for enterprise-type services, like Box or Google Cloud.

To authenticate with a service using the JSON Web Token method, you need:

  • The email that's used to set up the account with the third party

  • The endpoint that returns the token (which you'll find in the external API documentation)

  • The private RSA key that the service has provided

The private key needs to be formatted as the below example, including the '-----BEGIN RSA PRIVATE KEY-----' and '-----END RSA PRIVATE KEY-----':

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

Client-side SSL certificate

Using a Client-side SSL certificate is not as widely used as some of the other methods, but it's sometimes used in internal enterprise networks.

A client-side SSL certificate servers as a digital certificate that your app can you to authenticate with the server. It consists of two parts: The Certificate file content is the data contained in a digital certificate file (also known as a public key certificate). It contains information about the identity of the certificate holder (your app), such as a name and public key. It also holds information about the certificate issuer (the server you are connecting to), such as its name and digital signature.

The Key file content is the data contained in a private key file. It's used in conjunction with the public keys of both parties to encrypt and decrypt information.

Before granting access to a resource, many API providers will require that you authenticate.
Bubble lets you store two keys – one for testing and one for the live app.
This is what an OAuth2 connection to a Spotify user profile might look like.