LogoLogo
Try it outResourcesAPIsAddOnsBook a demo
  • Getting Started
    • Introduction to Beefree SDK
      • Create an Application
      • Installation and Fundamentals
        • Configuration parameters
          • Configuration Reload
          • Workspaces
          • Debugging the Beefree SDK Editor
        • Methods and Events
        • Authorization Process
        • How the UID parameter works
        • Set up two-factor authentication
        • Naming conventions
      • Development Applications
      • Manage Users
      • Manage Subscriptions
      • Installation and Fundamentals
    • Tracking Message Changes
    • Sample Code
    • Release Candidate Environment
  • Visual Builders
    • Email Builder
    • Page Builder
      • Integrating Page Builder
      • Embedding videos in a page
    • Popup Builder
      • Popup Builder - Getting Started
      • Testing and Integrating
      • Setting layout and size
        • Advanced settings
    • AI-Driven Design Creation
  • APIs
    • Content Services API
      • Authentication
      • Export
      • Convert
      • Row Processing
      • AI Collection
      • Brand Style
    • Template Catalog API
      • Authentication
      • Templates
      • Categories
      • Collections
      • Designers
      • Tags
    • HTML Importer API
      • Authentication
      • Import HTML
  • Forms
    • Form Block
    • Integrating and using the Form block
      • Passing forms to the builder
      • Form structure and parameters
      • Form layout customization
      • Allowed form fields
      • Edit form field modal
  • Rows
    • Reusable Content
      • Create Reusable Content
        • Pre-build Reusable Content
          • Implement Custom Rows
        • Save Reusable Content
          • Implement Hosted Saved Rows
          • Implement Self-hosted Saved Rows
            • Self-hosted Saved Rows Concepts and Tutorial
      • Sync Reusable Content
        • Implement Synced Rows
        • Initialize Edit Single Row Mode
      • Manage Reusable Content
    • Storage for Reusable Content
      • Hosted Saved Rows
      • Self-Hosted Saved Rows
  • File manager
    • File manager application overview
      • Mime Types and Groups
  • Server-side configurations
    • Server-side options
      • Toolbar options
      • Storage options
        • Configure your AWS S3 bucket
        • Connect your file storage system
      • Content options
      • Services options
      • Undo & Changes history
      • Custom JavaScript Libraries Injection
  • Other Customizations
    • Advanced options
      • Special Links and Merge Tags
      • Content Dialog
      • Custom Color Palette
      • Font management
      • Roles and Permissions
      • Smart Merge Tags
      • Commenting
      • Custom Attributes
      • Meta Tags
      • Custom Languages
      • Display Conditions
      • Advanced Permissions
      • Custom File Picker
      • Custom Headers
    • Appearance
      • Content Defaults
      • Custom Sidebar Position
      • Content Tile Sorting
      • Content Tile Grouping
      • Loading Spinner Theme
      • Custom Tab Layout
      • Themes
      • Custom CSS
        • Change Log
    • AMP for Email
    • Collaborative Editing
      • Co-editing Integration Guide
    • Mobile Design Mode
    • Multi-language Templates
    • Cards Style and Image Round Corners
    • Hover Effect for Buttons
    • Content Area Padding
    • Line Height
  • Data Structures
    • Getting Started
    • Schema Catalog
    • Simple Schema
      • Template Schema
      • Definitions Schema
      • Row Schema
      • Column Schema
      • Title Schema
      • Image Schema
      • Button Schema
      • Paragraph Schema
      • HTML Schema
      • Menu Schema
      • List Schema
      • Icon Schema
      • Divider Schema
    • Row Metadata
    • Form Validation Schema
    • Comments Schema
      • Change Schema for Comments
  • Builder AddOns
    • AddOns
      • AddOns Overview
      • Partner AddOns
        • Partner AddOns directory
        • Installing Partner AddOns
        • DeepL
        • Stability AI
        • Azure AI Vision - Image Analysis
          • Alternate Text Generation with AI
          • AI Alt Text Bulk Generation
        • AI Writing Assistant
          • Available Providers
            • OpenAI
            • Azure OpenAI
            • Anthropic
          • AI Providers and Data Security
          • AI-Generated Meta Tag Fields
          • Token Upselling
          • Apply a Brand Tone
        • Custom AI Writing Assistant
      • Custom AddOns
        • AddOn Development
        • Contribute to the Partner AddOn Marketplace
      • AddOns Configuration
      • AddOn FAQs
  • Resources
    • Error Management
      • onWarning
      • Beefree SDK Editor Errors
      • File System Provider errors
      • JSON Parser errors
      • Template Validation and Update
      • Template validation and update errors
    • Scheduled maintenances
Powered by GitBook
LogoLogo

Policies

  • Privacy & Cookies
  • Terms of Services
  • GDPR Compliance
  • Trust Center

Contact Us

  • Submit a request
  • Book a demo
  • Report a security issue

Resources

  • Developer website
  • Create a Developer Account

© Bee Content Design, Inc. San Francisco, CA | Part of Growens

On this page
  • Authorization Process Overview
  • Beefree SDK Client-side Configuration
  • Beefree SDK Server-side Login
  • Error Management
  • Handling error management
  • Error Responses

Was this helpful?

Export as PDF
  1. Getting Started
  2. Introduction to Beefree SDK
  3. Installation and Fundamentals

Authorization Process

PreviousMethods and EventsNextHow the UID parameter works

Last updated 9 months ago

Was this helpful?

Authorization Process Overview

The Authorization Process is an important step throughout your . This steps validates your Beefree SDK credentials and provides you with a token. Take the steps outlined in this document to ensure you accurately complete the authorization process.

Beefree SDK Client-side Configuration

Beefree SDK requires the host application to pass a container parameter in the This is the only required parameters for the configuration.

The following code sample shows an example of this parameter in the .

var config = {
    container: 'string'
}

Beefree SDK Server-side Login

To initialize your instance of the Beefree SDK builder, call the /loginV2 endpoint shown in the sample code below with your Client ID, Client Secret, and UID. The Client ID and Secret are available on the application details page of the . UID represents your user as described in .

Important: Do not put your Beefree SDK credentials in client-side code.

The Beefree SDK system uses OAuth2 as the authorization framework.

Example

POST /loginV2 HTTP/1.1
Host: auth.getbee.io
Accept: application/json
Content-Type: application/json
{
“client_id”: YOUR_CLIENT_ID,
“client_secret”: YOUR_CLIENT_SECRET,
“uid”: uid of choice
}

The following code sample displays an example JSON response.

{
    "access_token": "...",
    "v2": true
}

The Beefree SDK authorization service will return a temporary access token if the authentication is successful. The client application can use the full response that contains the token to start or refresh a Beefree SDK session.

The token you receive from the authorization server should be passed to the BeePlugin.create(...) as it is. We strongly suggest not altering it in any way. Also, don’t rely on the token response's content or structure. If you do, any change to the schema could make your integration stop working.

The token expires after 5 minutes for security reasons. Beefree SDK will refresh an expired token automatically for 12 hours without re-authenticating the application. Beefree SDK will trigger the onError callback when the token can't be refreshed automatically.

The following code sample displays an example of how to call the Beefree SDK endpoint, obtain a token, and then start it.

var req = new XMLHttpRequest();
req.onreadystatechange = function() {
  if (req.readyState === 4 && req.status === 200) {
    // Obtain token
    var token = req.responseText;
    // Call create method and pass token and beeConfig to obtain an instance of Beefree SDK
    BeePlugin.create(token, beeConfig, function(beePluginInstance) {
	// Call start method of beefree SDK instance
	beePluginInstance.start(template); // template is the JSON to be loaded in BEE
    });
  }
};

// This is a sample call to YOUR server-side application that calls the loginV2 endpoint on BEE the side
req.open(
	'POST', 	// Method
	'/YOUR_BACKEND_TOKEN_ENDPOINT', // your server endpoint
	false 		// sync request
);

Ensure to call the authorization endpoint server-side to protect your credentials.

Beefree SDK will keep this session alive for 12 hours from the login. After 12 hours, you have to manage the token expiration, as follows:

  1. Obtain a new token via the new authorization endpoint.

  2. Inject the token obtained from step one via the updateToken method. Reference examples of this in the following section.

The following code example shows how to inject the token in the current Beefree SDK instance:

// obtain a new token with a new LoginV2 call
// update the token in the current Beefree SDK instance
beePluginInstance.updateToken(token);

The following code example displays how to get the current JSON from the expiration error:

onError: function (error) {
  var code = error.code
  var detail = error.detail

  // the template the user was working on before the error occurred
  var currentJson = error.template
  ... 


  beePluginInstance.updateToken(token);
  // the beePluginInstance comes from the BeePlugin.create 
  ...

Error Management

When you set up an onError callback you will get the error object as a parameter.

From that object, you can grab the code property and use it as explained in the table below.

Code
Message
Detail

5101

Expired token cannot be refreshed

You need to do a new login and update the token in the current Builder instance using updateToken method.

5102

Expired token must be refreshed

You need to do a new login and create a new Builder instance using the new token, BeePlugin.create() and the current JSON template present in this event

Example scenarios:

  • The version is outdated

  • Beefree SDK releases a security fix and every client must refresh

Handling error management

The following code samples display how to handle the 5101 and 5102 errors.

Error management error 5101

onError: function (error) {
 var code = error.code
 var detail = error.detail
 switch (code) {
   case 5101: // re-login and update token in the beeInstance
var req = new XMLHttpRequest();
req.onreadystatechange = function() {
 if (req.readyState === 4 && req.status === 200) {
   // Obtain token
   var token = req.responseText;
   // Call update method and pass the new token existent BeePlugin instance
   BeePlugin.updateToken(token);
 }
};
req.open(
 'POST',  // Method
 '/token',  // The server side endpoint that calls BEE REST auth endpoint
 false   // sync request
);

     break
   case 5102: // re-login and create a new beeInstance
var req = new XMLHttpRequest();
req.onreadystatechange = function() {
 if (req.readyState === 4 && req.status === 200) {
   // Obtain token
   var token = req.responseText;
   // Call update method and pass token and beeConfig to obtain an instance of BEE Plugin
   BeePlugin.create(token, beeConfig, function(beePluginInstance) {
     // Call start method of bee plugin instance
     beePluginInstance.start(template); // template is the json to be loaded in BEE
   });
 }
};
req.open(
 'POST',  // Method
 '/token',  // The server side endpoint that calls BEE REST auth endpoint
 false   // sync request
);
     break
 }
},

Error management 5102

onError: function (error) {
 var code = error.code
 var detail = error.detail
 switch (code) {
   case 5101: // re-login and update token in the beeInstance
...
   case 5102: // re-login and create a new beeInstance
var req = new XMLHttpRequest();
req.onreadystatechange = function() {
 if (req.readyState === 4 && req.status === 200) {
   // Obtain token
   var token = req.responseText;
   // Call update method and pass token and beeConfig to obtain an instance of BEE Plugin
   BeePlugin.create(token, beeConfig, function(beePluginInstance) {
     // Call start method of bee plugin instance
     beePluginInstance.start(detail.template); // the template the user was working on before the error occurred
   });
 }
};
req.open(
 'POST',  // Method
 '/token',  // The server side endpoint that calls BEE REST auth endpoint
 false   // sync request
);
     break
 }
},

Error Responses

Example error response for unsupported media type Only Content-Type: application/json is allowed.

{
  "code": 5001,
  "message": "Unsupported media type 'application/x-www-form-urlencoded'",
  "status_code": 415
}
{
  "code": 5005,
  "message": "Invalid UID",
  "status_code": 400
}
{
  "code": 5002,
  "message": "Unable to authenticate with provided credentials.",
  "status_code": 401
}

Example error response for disabled apps. Contact support if you encounter this error.

{
  "code": 5003,
  "message": "Application is disabled.",
  "status_code": 403
}

Reference to learn more about UID.

Note: When a refreshable token expires, Beefree SDK receives a and attempts to refresh it automatically. 401 errors are expected and part of the process.

Once you obtain the token, the object is passed to Beefree SDK to set up your customization options, for example setting the editor’s language to “Spanish”.

Then, you can use Beefree SDK methods to on your page.

Example error response for an invalid UID. Look at the properties of .

Example error response for invalid credentials. Obtain your credentials using the .

Beefree SDK installation process
client-side configuration.
client-side configuration
Beefree SDK developer portal
How the UID parameter works
How the UID parameter works
configuration parameters
start your instance and display the editor
UID parameter
authorization process
401 error