Getting started

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > OData services >

Getting started


Bizagi provides an API featuring OData services, as described at Bizagi API.

In order to explore and validate what properties and options these Bizagi OData services support, consider the concepts applicable.



General recommendations

Consider the following notes:


Using Postman.

For a quick start, we strongly recommend using Google Chrome and an extension plug-in called Postman.

Extensions such as Postman (or you may choose to use a similar one such as Advanced REST Client, allow you to invoke OData services while being able to customize the information that gets sent in the header of the request (which is not possible through a browser).

For information about Postman, refer to


Configuring the potential of Stakeholders.

For ideal results and in order to fully seize the data considered by the Bizagi OData services, we strongly recommend having modeled processes in your project which make use of the Experience design.

Throughout Experience design, ensure that you have created Stakeholders and that you have them configured in your Work portal to your different users, so that Bizagi is presenting data differently according to the given Stakeholder.




The image above shows a user named Tom Hall which is set as a Legal Area Worker Stakeholder.

There are some few specific services which are an exception to the above rule; for instance those aimed at returning information about cases, which do not require Stakeholder configuration.


What you need to do

To invoke Bizagi OData services, consider the following high-level outline:


1.  Registering an OAuth application.

This first step is about granting access to an external application, while creating appropriate access keys.

This is a requirement in order to use OData services.


2. Authenticating with OAuth.

This step uses Postman to establish authenticated communication with the OData services.

Once using the access keys, you will get an access token to make further requests.


3. Invoking OData services.

As a last step, any number of invocations can be made while using the access token (still considering Postman).




In order to easily test drive the Bizagi OData services, follow these steps.


1. Registering an OAuth application.

Once you have users set as Stakeholders and use comprehensively, the Experience design features in Bizagi, go to the Work portal.


Click on the OAuth2 Applications option available under the Admin menu in order to grant access to an external application.




Notice this option lists services being accessed by Bizagi devices, but it allows you to include additional applications that represent granted access to the services by getting appropriate access keys.

Click on the option to add a new record in this table:






Note that for the default and system settings, you may only choose to edit the token's lifetime, which determines a number of minutes after which a token expires (in order to enhance the security employed by these tokens, especially regarding replay attacks).





When defining the new application, ensure you consider the following details:

Name: Give a unique and representative name.

Grant type: Possible values are: Authorization Code, Client credentials, or all.

More information about these values and when to use each best, is instructed at Bizagi API OAuth concepts.

Web Site: Specify an associated Web site URL.

Allowed Scope: Possible checkboxes to tick are: API, or Login.

It is recommended to always enable API in order to grant access so that you can make full use of the OData services.

Enable Login specially when choosing to use Authorization Code as the Grant type.

User name: (Applies when using Client credentials). Type the name of an existing Bizagi user, and ensure you select it from the suggested list of matching users (includes the domain information).

Redirect strategy:  (Applies when using Authorization Code). Possible values are: Web Application, Mobile Title Bar Browser, and Mobile Localhost Port.

A redirect strategy defines which clients will be able to make use of this application.

For this initial test and for a general use, you may consider setting Web application.

Nonetheless, an usually recommended approach is indeed to use Web application so that a server (capable of processing requests through endpoints) invokes the Bizagi API, while having in turn, mobile apps or any other type of clients invoke services from such server.

Redirect URI: (Applies when using Authorization Code). Define the URL to which there will be directed in the callback once an user inputs his/her credentials.

You will always need to define a URL using HTTPS.

Token lifetime: Define the number of minutes for which a same token is valid and can be reused for another invocation (usually to enhanced security while avoiding replay attacks).




Note it is recommended to use these combinations, involving usually 2 different applications:


For Data services:

Grant type: Authorization code, Allowed scope: Login and API.  


For Metadata services:

Grant type: Client credentials, Allowed scope: API.





Notice how in this example, the registered application will authenticate on behalf of the agilityCorp\TomH user.


Once you are done, click Save.

You will notice that your new registered application is listed along with its access keys.

Access keys to be used and copied to the clipboard, are: Client Id and Client Secret.





2. Authenticating with OAuth.

Once that you have copied the Client Id and Client Secret, through Postman we establish authenticated communication.

Before doing so, note that Bizagi expects the credentials as a single string encoded in base64.


2.1 In order to encode this as a single string, carry out the following:

Copy the Client id first and append a colon (:) to finally add the Client secret.

The following format is employed, disregarding the [] characters:

[Client Id]:[Client Secret]

Encode this string with base64.

For this you may rely on external web sites such as, or use your own program.


In the end, you will have a resulting string with the credentials contained within, and we will refer to it as the Encoded credentials:




2.2 Open the Postman extension plug-in and use this encoded string to authenticate to the OAuth service.




2.3 First make sure you input the URL of this service for your specific Bizagi project.

Ensure you use an HTTP POST action with such URL set as:




[your_bizagi_project_url]: Corresponds to the URL where end users access the Bizagi Work portal.

For instance for an on-premise Bizagi project, such URL would be:


While for Bizagi PaaS projects, such URL would be:




Specify as well that No Auth is employed.




2.4 Switch to the Headers tab and specify:

Content-type: application/x-www-form-urlencoded

Authorization: Input the Basic keyword, add a blank space and then add the Encoded credentials obtained in a previous step.

The following format is employed, disregarding the [] characters:

Basic [Encoded credentials]





2.5 Finally switch to the Body tab tick the raw setting to include this line in the body:






Notice that the possible values for grant_type are: client_credentials or authorization_code.

Similarly, possible values for the scope are: login, api or all.

However, the use of authorization_code needs to be done in a client application where it implements this spec adequately (while sending out credentials).


At this point you may click Send, which triggers the request to authenticate.

A successful response returns an access_token along with other data relevant to it:




3. Invoking OData services.

Once you get the access_token, you may use it for a new invocation and test drive the OData services.

This time and in order to do a quick test, you may use an HTTP GET action to fetch some basic data.


When doing so, make sure you use a OData service URL this time.

For a quick start, you may use:



Then configure:

Authorization: Input the Bearer keyword, add a blank space and then add the access_token obtained in the previous step.

The following format is employed, disregarding the [] characters:

Bearer [access_token]

Content-type: application/json




At this point you may click Send, which triggers the request to fetch data in JSON format.

A successful response for this specific example and URL, returns the name of the Stakeholders to which the authenticated user belongs to:




Notice how the set Stakeholder for this user (agilityCorp/TomH having full name as Tom Hall) is Legal Area Worker.




Consider that the access_token expires as set through its token lifetime settings, and therefore you may need to launch a new invocation by first authenticating again with the Encoded credentials.



You may of course choose to include filters or navigate data returned by the response.

In order to learn about the filters and options to restrict which data you want to handle, refer to Querying options.


At this point that you have made a first invocation to these services, you may further explore the resources and different alternatives to query them.

For more information about all of these services, refer to Data services or Metadata services.

For additional information about properties, querying options and other useful concepts when invoking these services, it is recommended to browse first the Basic concepts.