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.
Blueworks Live offers two types of service IDs, at the account level and at the user level.
Account-level service IDs
- Open the Admin page, and go to the tab.
- In the Blueworks Live API section, enable the option for Enable API access via service IDs.
- Click Create service ID.
- Enter a name and a description for your service ID.
- 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.
- 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) orTaskList
(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.
- 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
- Open the Admin page, and go to the tab.
- In the Blueworks Live API section, enable the option for Enable API access via user service IDs.
- 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 and click
Export user service IDs.