Blueworks Live API

Overview

The Blueworks Live API provides access to a limited subset of the available Blueworks Live functions, such as search, list process details, and start work instances. All access to the API requires authentication by using an access token. It either has global access to the account or can be restricted to what is permitted for a specific user. Viewers and community members do not have access to the API.

URL for Curl

Authentication

Authentication is required for Blueworks Live API calls.

To do authentication, use OAuth 2 authentication with client credentials. Automated systems use a Service ID/User Service ID to request a token.

Responses

401 UNAUTHORIZED

The token has expired or is unauthorized at the time to complete the action, but authorization might be possible.

403 FORBIDDEN

The user is authenticated, but the action is disallowed for the user. Possible cause is that a Service ID that was not in the User Management category tried to call the /scr/api/UserList. Another possible cause is that the APIs isn't enabled by the administrator on the Account Information tab.

User Service ID authentication

curl.exe -k -i -H "Content-type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&client_id=
my_client_id&client_secret=my_client_secret&consent_type=user_consent" "https://your_server_url/oauth/token"

• Replace my_client_id with the Client ID value from the Service ID JSON file.
• Replace my_client_secret with the Secret value from the Service ID JSON file.
• Specify the grant_type as client_credentials.
• Specify the consent_type as user_consent.
• Replace your_server_url with the server that you are making the POST request to, for example, https://ServerName/oauth/token.

curl -i -H "Authorization: Bearer access_token" "https://your_server_url/scr/api/UserList"

The response includes only the resources that the specified user has access to or is permitted to see in the account. For example, if the /bwl/blueprints API is called, only the blueprints that are visible to the User Service ID owner are shown. Or, if the /bwl/blueprints/{blueprint-id} API is called to get the details of a specific blueprint and the blueprint is not accessible to the User Service ID owner, the command produces a "403" response.

For information about OAuth 2, see The OAuth 2.0 Authorization Framework.

Service ID authentication

curl.exe -k -i -H "Content-type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&client_id=
my_client_id&client_secret=my_client_secret" "https://your_server_url/oauth/token"

• Replace my_client_id with the Client ID value from the Service ID JSON file.
• Replace my_client_secret with the Secret value from the Service ID JSON file.
• Specify the grant_type as client_credentials.
• Replace your_server_url with the server that you are making the POST request to, for example, https://ServerName/oauth/token.

curl -i -H "Authorization: Bearer access_token" "https://your_server_url/scr/api/UserList"

APIs that can be called only on behalf of a specific user (such as FollowedProcesses and TaskList) require a user context. Other APIs optionally allow you to specify a user context. To provide the user context, pass a X-On-Behalf-Of header in your request with the username as the value. The response includes only the resources that the specified user has access to or is permitted to see in the account. For example, if the /bwl/blueprints API is called with a user context, only the blueprints that are visible to the specified user are shown. If the /bwl/blueprints/{blueprint-id} API is called with a user context to get the details of a specific blueprint and the blueprint is not accessible to the specified user, the command produces a "403" response.

Not all APIs are enabled for user context. If you try to pass a user context to an API that is not enabled for it, the command produces a "400" response.

For information about OAuth 2, see The OAuth 2.0 Authorization Framework.

Rate Limiting

IBM Blueworks Live applies a rate limit that determines how often an API can be called within a specific period. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users.

Once the rate limit of the account for the API is exceeded, the next request is rejected with status code 429 and response header Retry-After. This status code indicates the number of seconds when the next request can be made.

OpenAPI specification

The OpenAPI specification is a standardized, machine-readable format for describing RESTful APIs. The OpenAPI specification provides you with a clear and comprehensive understanding of APIs, enabling easier interaction and integration.

The specification includes detailed information about:

Examples

Use the following Java template as a basis for your own projects. The example uses the JSON4J library from the Apache Wink project to decode the JSON responses sent back by the API.

1. Download the following Java files:

   • The following example programmatically runs /scr/api/UserList and parses the results.

     RestApiClientTemplate.java

   • The following example programmatically runs /bwl/glossary-values/{category} and demonstrates how to work with a rate-limited API.

     RestApiRateLimitClientTemplate.java

   • The following example demonstrates how to call the /scr/api/Search API.

     SearchExample.java

2. Download the following Java archive (JAR) file:

   json4j

3. Compile the following example:
   • For Windows operating systems,

     javac -cp .;wink-json4j-1.3.0.jar RestApiClientTemplate.java
     javac -cp .;wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate.java
     javac -cp .;wink-json4j-1.3.0.jar SearchExample.java

   • For Linux operating systems,

     javac -cp ./wink-json4j-1.3.0.jar RestApiClientTemplate.java
     javac -cp ./wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate.java
     javac -cp ./wink-json4j-1.3.0.jar SearchExample.java

4. Run the example and change credentials to valid values.
   • For Windows operating systems,

     java -cp .;wink-json4j-1.3.0.jar RestApiClientTemplate
     java -cp .;wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate
     java -cp .;wink-json4j-1.3.0.jar SearchExample

   • For Linux operating systems,

     java -cp .:./wink-json4j-1.3.0.jar RestApiClientTemplate
     java -cp .:./wink-json4j-1.3.0.jar RestApiRateLimitClientTemplate
     java -cp .:./wink-json4j-1.3.0.jar SearchExample