Creating and using service IDs

Service IDs provide access to Blueworks Live APIs from your automated systems, for example systems that generate weekly reports or do monthly backups. When the system calls an API, it can use a service ID instead of authenticating with a user ID and password. You can also enable users to create their own user service IDs.

The service ID has client credentials, which OAuth 2, the authorization framework, calls the Client ID and Secret. Service IDs never expire, although you can revoke them if you choose.

To authenticate, the automated system sends the client credentials and Blueworks Live returns a short-lived token that the system can use to call the API. When the token expires, the system requests a new one.

Note: A service ID is not a user ID. It does not use up a license, and it does not show up on the User management tab or in any list of users. You cannot use it to log in to Blueworks Live.
Any changes to Blueworks Live artifacts made by programs using service IDs show up in the activity stream, the same as changes made by individual users.

Blueworks Live offers two types of service IDs, at the account level and at the user level.

Account-level service IDs

You must be an account admin to create an account-level service ID. To create a service ID:
  1. Open the Admin page, and go to the Settings > Account information tab.
  2. In the Blueworks Live API section, enable the option for Enable API access via service IDs.
  3. Click Create service ID.
  4. Enter a name and a description for your service ID.
  5. Select a category. Each service ID has a category, which determines the set of APIs that it can access, and it cannot be used for APIs outside of that category.
    • Artifact authoring: Provides access to APIs for uploading files, creating revisions. and adding or updating glossary values.
    • Artifact reporting: Provides access to APIs for retrieving information about any artifact in the account. The access granted is account-wide and not restricted by space permissions.
    • Account activity reporting: Provides access to APIs to retrieve information about account activities or a user's activity stream.
    • User management: Provides access to APIs for user provisioning and user information.
    • Work management: Provides access to APIs for querying data about in-flight and completed tasks, launching new work, and completing or commenting on existing work.
  6. If available, in User context you can select the option to allow this service ID to be called on behalf of a user in this account. Many APIs must be called on behalf of a specific user and require you to provide a user context, for example FollowedProcesses (an API that determines the processes that a user is following) or TaskList (an API that returns a list of the tasks assigned to the user).

    Other APIs can optionally be called with a user context, for example blueprints. If a user context is provided, only the elements that are visible to that user are included in the response.

    For a list of available APIs in each category, see the Blueworks Live API.

  7. Click Create.

    The client credentials are downloaded to your machine. Save this file and share it only with authorized personnel who will be implementing automated API calls, for example, the development team who are implementing weekly reports. The service ID file cannot be downloaded again. As its owner, you are responsible for ensuring that it is used only for its intended purpose.

If only service IDs are enabled in your account, you must share this service ID with users for them to use. You are also responsible for ensuring that the service ID is revoked if it is no longer required or if you think that it might be compromised. After you revoke a service ID, you can delete it.

User service IDs

You can allow users to create individual user service IDs to call APIs.
Note: User service IDs are available for Editors only.
  1. Open the Admin page, and go to the Settings > Account information tab.
  2. In the Blueworks Live API section, enable the option for Enable API access via user service IDs.
  3. Go to the User management tab. In the API access column, you can select the users who require API access. These users can now create service IDs for themselves in their user settings. In the user settings, you can create service ID for the required categories, similar to the account-level service ID. You can also update or revoke them.

You can export a CSV file of all user service IDs. From the User management tab, click the Export menu icon menu and click Export user service IDs.