Authorization process in detail

To initialize your instance of BEE editor, call the endpoint shown in the sample code below with your Client ID and Client Secret, which are available in the application details page of the BEE Plugin developer portal (if you don’t have an account, sign up).

The BEE Plugin system uses OAuth2 as the authorization framework.




POST /apiauth HTTP/1.1
Host: auth.getbee.io
Accept: application/json
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

We strongly suggest not to put your BEE credentials in front-end code - they are specific to your account, and they could be easily read and used by other people.

The

grant_type

parameter, which was mandatory in previous versions of BEE Plugin, can now be omitted.

If the authentication is successful, the BEE Plugin authorization service will return a temporary access token to the client application. The token can then be passed by the client application to the BEE Plugin resource server in order to start the session.

Note: the entire response from the auth endpoint must be passed here, not just the access token you receive. The access token itself must also be converted to valid JSON with JSON.parse(token).

The token you receive from the authorization server should be passed to the BEE Resource server as it is. We strongly suggest not to integrate or alter it in any way - if so, any change on our side could make your integration stop working.

The token expires after 5 minutes for security reasons. An expired token can be refreshed for 7 days without re-authenticating the application. Once the application has started communicating with the BEE Plugin resource server, the plugin will take care of refreshing the token automatically, as long as someone is actively using the editor, with a heartbeat every 28 minutes.

If a token has expired, the plugin receives a 401 error and attempts to refresh it automatically. The 401 errors are nothing to worry about as they are part of this process.

Here is an example of how to call the BEE Plugin endpoint, obtain a token and then start the plugin:




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 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
);

You can call the authorization endpoint clientside or serverside: just make sure to use HTTPS if your call is from a web client.

Once you obtain the token, configuration parameters are passed to BEE Plugin to set up the options you wish (e.g. setting the editor’s language to “Spanish”).
Then, you can use BEE plugin methods, start your instance and display the editor in your page.