Authorization Process

Authorization Process Overview

The Authorization Process is an important step throughout your Beefree SDK installation process. This step 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 NPM Package

Prior to getting started with the authorization process, ensure you reference the Beefree SDK official npm package. Reference both the wrapper and the GitHub repository to get the latest information.

Package Installation

You can install Beefree SDK using either npm or yarn:

Using npm

npm install @beefree.io/sdk

Using Yarn

yarn add @beefree.io/sdk

Package Details:

• TypeScript Support: Included

• License: Apache-2.0

• Repository: Beefree SDK GitHub

Beefree SDK Client-side Configuration

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

The following code sample shows an example of this parameter in the client-side configuration.

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 Beefree SDK developer portal. UID represents your user as described in How the UID parameter works.

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
}

Reference How the UID parameter works to learn more about UID.

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 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.

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

You can reference /loginV2 examples in the following Quickstart Guides:

• React

• Vue

• Angular

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

Once you obtain the token, the configuration parameters 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 start your instance and display the editor on your page.

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
beeInstance.updateToken(token);

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, 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

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
}

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

{
  "code": 5005,
  "message": "Invalid UID",
  "status_code": 400
}

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

{
  "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
}