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 in Bizagi API.


General recommendations

Using Postman.

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

Extensions such as Postman (you can use a similar one such as Advanced REST Client, let you 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 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.

Through Experience design, make sure that you have created Stakeholders and have associated the users in your Work Portal to the relevant Stakeholder, so Bizagi can present 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 a 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

Here is a high-level outline of what you do to invoke Bizagi OData services:


1.  Register an OAuth application.

This first step is granting access to an external application and creating appropriate access keys.

This is a requirement to use OData services.


2. Authenticate with OAuth.

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

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


3. Invoke OData services.

As a last step, you can make any number of invocations can be through Postman while using the access token.



To easily test drive Bizagi OData services, follow these steps.


1. Register an OAuth application.

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


Click the OAuth2 Applications option under the Admin>Security menu to grant access to an external application.




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

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




When defining the new application, provide the following details:

Name: provide a unique and representative name.

Grant type: Possible values are: Authorization Code, Client credentials, All, or Bearer token.

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

Web Site: Specify an associated web site URL.

Allowed Scope: Possible checkboxes to check are: API, Login, User Sync, OData query or RPA.

oWe recommend you enable API to grant access so you can make full use of the OData services.

oEnable Login especially when using Authorization Code as the Grant type.

oEnable User Sync when synchronizing users using SCIM.

oEnable OData query when using the Query resource of the OData services.

oEnable RPA when using Automation Anywhere Callbacks.

User name: (applies when using Client credentials). Provide the name of an existing Bizagi user. Make sure 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.

oWeb Application: Redirects the user to a web URI using the code obtained from the authorization server.

oMobile Title Bar Browser: Value used when the application redirects the user to a mobile device app. As mobile devices don't have an endpoint, the request is redirected sending the authorization code in the title HTML tag. So the mobile device can get it from there.

oMobile localhost port: Bizagi sends the code to https://localhost:port/ where a mobile device can get the one sent by the authorization server.

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

For this initial test and for general use, consider selecting Web application.

A standard approach is to use Web application so a server capable of processing requests through endpoints invokes the Bizagi API, while mobile apps or other type of clients invoke services from such server.

Redirect URI: (Applies when using Authorization Code). Define the URL to which the user is directed in the callback after providing their credentials.

You always need to define the URL using HTTPS.

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



We recommend that you use these combinations, usually involving tow different applications:

For Data services:

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

For Metadata services:

Grant type: Client credentials, Allowed scope: API.




In this example, the registered application  authenticates on behalf of the agilityCorp\TomH user.


Once you are done, click Save.

Your new registered application appears in the list with its access keys.

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




2. Authenticate with OAuth.

Once you have copied the Client Id and Client Secret, establishing authenticated communication through Postman.

Note that Bizagi expects the credentials as a single string encoded in base64.


2.1 To encode the credentials as a single string:

Copy the Client id first and append a colon (:), then add the Client secret.

Here is the format, disregarding the [] characters:

[Client Id]:[Client Secret]

Encode this string with base64.

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


The result is a string containing the Encoded credentials:




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




2.3 Input the URL of this service for your specific Bizagi project.

Use an HTTP POST action with the URL set as:



Make sure that:

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

For an on-premise Bizagi project, the URL would be:


For Automation Service projects, the URL would be:



Specify as well that No Auth is employed as the authorization type.




2.4 On the Headers tab, specify:

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

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

Use the following format, disregarding the [] characters:

Basic [Encoded credentials]




2.5 Finally, on the Body tab, check the raw checkbox to include this line in the body:






The possible values for grant_type are client_credentials and authorization_code.

The possible values for scope are login, api and all.

You need to use authorization_code in a client application that implements this spec adequately (while sending out credentials).


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

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




3. Invoke OData services.

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

To do a quick test, you can use an HTTP GET action to fetch some basic data.


Make sure you use an OData service URL.

For a quick start, use:




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

Follow this format, disregarding the [] characters:

Bearer [access_token]

Content-type: application/json




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:




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




The access_token expires after the time you set for its token lifetime setting elapses, so you may need to launch a new invocation and authenticate again with the Encoded credentials.



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

To learn about filters and other options to restrict which data you will work with, refer to Querying options.


At this point that you have made a first invocation to these services. You can now explore the resources and different alternatives to query them.

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

For additional information about properties, querying options and other useful concepts when invoking these services, browse Basic concepts.