Authorize your API calls

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

Business Catalyst uses OAuth 2.0 as an authorization method for API calls.

REST API calls can only be made form the context of an app. Resources returned by v3 API endpoints however can also be accessed using module_data, take a look at the Consuming APIs in the front-end using module_data article for more details and samples on this module.

To make API calls you will need to authorize the app before navigating away from its landing page (we will detail below why you need to complete the authorization sequence before navigating away).

Implementing authorization

Every app you build will have either an Admin console menu or ribbon entry that users click to launch the app and a landing page that is displayed after the user clicks the Admin Console menu entry.

In the previous page, the Introduction article we described how to create the menu or ribbon entry and explored the customization options available.

The context API calls will run in

Apps run at all times on a completely different domain than the site you are running it on.

This might sound confusing at first - for security reasons Business Catalyst dynamically generates a different domain for each app you run on your site. Each application you install or develop on a site will have its own domain to run under.

Here is how the application custom domains are formatted:

For example, assuming my site ID is 1234 and my app key is first-app-hello-world the URL the app's landing page will be opened with is:

To get a better idea of how the custom domain works like let's go back to the "Hello world" example app . At step 6 of the tutorial we created a second page and inserted a link to it on the app's landing page.

If you right click the app's panel and open the frame in a new tab like so:

the special domain will open up in a new tab. That is the domain Business Catalyst will use to load all your app's assets and the context all API calls will run on.

The access token

All the API calls you will make from your app will need to use that token for authorization. The system automatically creates the cookie access_token and uses it to store the authorization token.

If you need to store the token to a variable you can either read the contents of the access_token cookie or, alternatively use the bcapi.js SDK. Make sure the bcapi.js script and its dependencies are linked in your landing page and simply call this method:

You can also write your own code to get the token and process it according to your needs.

Authorization complete

At this point the authorization is complete. The system has launched the app in its own environment on the custom domain, generated the token and passed it in the URL of the landing page, created the access_token cookie to store the actual token.

You can now open up other pages of your app or start making API calls.