REST API: Define Clients and Generate Keys for Integrations with
Clarity

ccppmop1581
Configure the REST API key authentication to enable business users to integrate data between the
Clarity
and other client applications. Integration architectures can allow users to authenticate through the REST API and accomplish certain
Clarity
actions without going into the user interface. Through API keys, user SSO credentials, access rights, and status settings match their own personal API token.
For example, a CA Agile Central (Rally) integration could make webhook calls to read
Clarity
project data personalized for the current user. For project managers, third-party integration could read and update resource allocation data in
Clarity
based on external application triggers such as other users updating a JIRA Kanban board.
2
REST API Prerequisites
API Administrators, Architects, and Lead Developers
: Contact your
Clarity
application administrator for the following rights to configure the REST API feature and define clients in
Clarity
Administration menu:
  • Administration - Access
  • Administration - Authorization
  • API - Access
    Administration - Authorization
    is the same right for managing resources in the
    PPM classique
    Administration menu and includes the
    Administration - Navigate
    right. For most administrators, the
    PMO System Administrator
    group already provides these rights.
Business Users, Developers, and Test Users
: Contact your administrator for the following access right to generate a key that you can use to access a client application integrated through the REST API.
  • API - Access
As an administrator, grant each user one or more additional access rights to view or edit data in specific functional areas such as projects or resources. See in the Reference section.
REST API Key Hierarchy
rest_api_hier.png
Admins: Configure REST API System Options
As an administrator, you can enable or disable the API key feature.
Follow these steps
:
  1. In
    PPM classique
    , click
    Administration
    ,
    General Settings
    ,
    System Options
    .
  2. Scroll down to the
    API
    section and complete the following fields:
    • Enable API Key Based Access
      : By default, this checkbox is clear. To enable the feature, select this option. If you clear this option later, users can no longer generate API keys.
    • Salt for Encrypting API Keys
      : By default, each new installation receives a preset salt value for key encryption. We recommend that you change the value after an installation or upgrade to satisfy the security requirements in place at your organization.
      Salt Tip 1
      : We recommend that you change the value after an installation or upgrade to satisfy the security requirements in place at your organization.
      Salt Tip 2
      : Be careful to minimize future changes to the salt field. After users create keys, if you change the salt value, all existing keys are no longer valid.
    • Maximum expiration in days for API keys
      : You can adjust the default value of 90 days to set your own maximum number of days. The value that you set determines the maximum possible duration or lifespan for each active key from its creation date. When a user generates a key and sets the
      Expiration Date
      for the key, the application enforces this limit. The user must enter a valid
      Expiration Date
      for the key that does not exceed the calculated maximum. Keys expire automatically when the expiration date arrives.
    • Maximum number of keys allowed per user
      : This value determines how many keys each user can create for all clients defined in the system. For any single client, no more than 20 keys can be created and stored for each user.
  3. Click
    Save
    .
enable_keys.jpg
In SaaS environments, the checkbox above serves as a single master switch to turn the API key feature on or off. However, in on-premise environments, administrators can also disable REST API access through a CSA application server setting as shown below.
image2019-3-13_16-37-44.png
If a user receives
API-1029: Authentication Error
, verify that
Disable REST API Access
is clear and that each user has the
API - Access
right.
Admins: Define REST API Client Applications
Before you can integrate with your client applications through the REST API, define each target client application.
Follow these steps
:
  1. Log in to
    Clarity
    .
  2. In the main menu, click 
    Administration
    .
  3. Click API Keys.
    image2019-2-28_15-53-16.png
  4. Click 
    CLIENTS
    .
  5. (Optional) Click
    ADD FILTER
    to search for existing client entries.
  6. (Optional) Apply or save a view. You can also work in an unsaved view.
  7. To add a new client, click 
    New Row
    .
    1. In the
      ID
      field, enter a required unique identifier for your new integrated client application.
    2. In the
      Name
      field, enter the name of your integrated client application.
    3. The application selects the
      Active
      checkbox for you. To set the client to inactive, clear the checkbox.
  8. To show or hide other columns, click 
    Column Panel
    .
    The following image shows an integration client:
    image2019-2-28_15-59-12.png
  • Your client ID must be passed with the API key in future REST API calls.
  • This release does not support deleting a client. Instead, you can deactivate it.
  • If you clear the
    Active
    checkbox, the client is now inactive and all keys created by all users for that client are temporarily disabled. Users cannot generate new keys while a client is disabled. When the administrator activates the client again, users previous keys work again and they can also generate new keys.
Users: Generate Your Own REST API Key
REST API keys serve as tokens that permit authorized users to exchange data between
PPM classique
and a pre-defined client application.
At any given time, each authorized user can store up to 20 keys for each client.
Users are limited to creating no more than 20 keys for a single client.
That statement is not entirely true. A user could create 20 keys and their administrator could delete two (2). Now the user could create two more if their system settings (keys per user) allow. A user might create any number of keys as permitted; however, at any single time for a single client, the application can store up to 20 keys for each user.
Follow these steps
:
  1. Log in to
    Clarity
    .
  2. Click your name and avatar image in the top right corner.
    The application menu appears. Menu items include
    SETTINGS
    ,
    API KEYS
    ,
    ABOUT
    ,
    HELP
    , and
    LOG OUT
    .
  3. In the application menu, click
    API KEYS
    .
    image2019-2-28_14-28-11.png
  4. On the
    API Keys
    page, click 
    New Row
    .
    1. In the required
      Access Type
      field, select the type of access you want to allow with this key:
      • All Access
        :
        All Access
        means that the key authorizes each user to perform the maximum amount of functionality as determined by their
        Clarity
        access rights. Even users with
        Delete
        access rights on one or more objects (such as projects or resources) cannot delete items through an integration unless they have an
        All Access
        key.
      • Read/Edit
        : This type of access allows users to read, create, and update Clarity data.
      • Read-Only
        : With this access type, users can only read data in
        Clarity
        ; they cannot make any changes.
    2. In the
      Client
      field, select an integrated client application to pair with this API key. You or another authorized user already set up these client applications in a previous procedure on this page.
    3. Enter a required
      Name
      for this integration (
      key-client
      pair) and a required
      Expiration Date
      for the key.
    4. The application selects the
      Active
      checkbox for you. You cannot disable a key.
    5. The application fills in your name in the
      Owner
      field. You cannot change the owner.
      image2019-3-12_17-23-10.png
  5. After all required fields are complete, your API key appears (see the image below).
    This exclusive appearance of the
    New API Key
    modal pop-up is the one and only time you can view and copy your key.
  6. Click
    COPY KEY
    . You cannot close the page until the key is copied to the clipboard of your current operating system.
image2019-3-13_16-40-7.png
Also make a note of the
Clarity
server URL and your
Client ID
for this key. If you have a credentials application or secure password database, you can use it to store your server URL, client ID, and API key. You may also want to make a note of the expiration date. If you paste your key into a temporary application such as Notepad, be sure to use it in your client application.
  • Keys are self-contained entities and include their associated client, owner, expiration date, and user access type.
  • Keys in queries run in the context of their owner.
    Clarity
    access rights for the owner apply dynamically and are loaded from the database for each instance of a REST API call.
  • Keys are only available once. If you lose a key, regenerate a new one.
  • Keys are not stored in the database. Only the metadata about the key is available in the database.
  • Keys from Company A cannot be used with the
    Clarity
    server for Company B. The encrypted keys contain their own key-level salt codes for added security.
Admins: Monitor Keys and Clients
As an administrator, you can view all clients and all the basic key information for the keys created by individual users. You can also disable a client and all its child keys.
For security, no one, not even administrators, can ever create a key for another user, or view the REST API keys generated by other users. They are generated by authorized users only, and are available to copy immediately and then permanently disappear from view.
  1. Log in to
    Clarity
    .
  2. In the main menu, click 
    Administration
    .
  3. Click API Keys.
  4. Click
    KEYS
    .
    1. Administrators can monitor the list of keys for each client generated by one or more owners. You can view the access type, the active status, owner, and expiration date. You might be asked by business users to verify one or more field values to help troubleshoot implementations.
    2. When appropriate, to delete a key, right-click and choose
      Delete Row
      .
  5. Click
    CLIENTS
    .
    1. To disable a client, clear the
      Active
      checkbox.
    2. To enable a client, select the
      Active
      checkbox.
image2019-3-13_16-42-28.png
  • The
    KEYS
    and
    CLIENTS
    grids support your choice of filters, columns (show or hide), and saved views.
  • You can also click a row and then click
    DETAILS
    at far right to open the configurable
    Details
    panel.
When you upgrade or refresh a
Clarity
SaaS hosted instance (for example, from staging to production), the key metadata moves from the source environment to your new target environment; however, the keys from the previous environment no longer work. A new salt value takes the place of any older value and only new keys will work. As part of your post-refresh cleanup activities, administrators must manually delete the old keys for users. Another option is to deactivate the client for those old keys. Then, create new clients and keys.
REST API Key Examples
Your administrator enabled the feature and defined one or more integration clients. Now, as a business user or an application integration designer, you want to use your REST API keys to access
Clarity
data.
  1. Follow the steps explained earlier in this article from the start. Make a note of the Client ID for your integration target application, the URL of your
    Clarity
    instance and REST API object path, and copy your REST API key.
  2. To verify the calls, use a REST client tool with the following settings:
    Setting
    Parameter
    Value
    Basic REST Structure
    Method
    GET
    Request URL
    http://<ppm_server>:<port>/ppm/rest/v1/<object_class>
    Headers
    x-api-ppm-client
    <my_client_ID>
    Authorization
    Bearer <MY_REST_API_KEY>
    ContentType
    application/json
    In our example, we are setting the
    <object_class>
    to
    projects
    .
  3. Click
    Send
    .
  4. Verify that the response Status shows 200 OK.
The following two screenshots show an example of a REST API GET call for a list of projects using Postman:
image2019-6-5_15-48-43.png
In Postman, set the
Authorization Type
to
Bearer Token
and paste your key into the
Token
field.
image2019-6-5_15-52-25.png
The following image shows a similar example using Advanced REST Client:
image2019-6-5_15-38-44.png
The following sections show the request headers for an integration call with a client named CLIENT_MY-APP-2:
Request Header
x-api-ppm-client: CLIENT_MY-APP-2 Authorization: Bearer J0eXAiOiJKV1QiLCJhbGciOiJeyJzdWIiOiJhZG1pbiIs...0MTU2NTMyMzIwMCwCcUxxvX260ObmURVRzzY
Response Body
{ "_pageSize": 25, "_self": "https://ppmstage02:8043/ppm/rest/v1/projects", "_totalCount": 50, "_next": "https://ppmstage02:8043/ppm/rest/v1/projects?offset=25", "_results": [ { "_internalId": 5012672, "code": "csk.appChange", "name": "Application Change Template", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5012672" }, }, { "_internalId": 5013763, "code": "PR1027", "name": "Data Warehouse Performance Tuning", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5013763" }, { "_internalId": 5013764, "code": "PR1011", "name": "eBusiness Mobile Network", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5013764" }, { "_internalId": 5013765, "code": "PR1022", "name": "Email SAN Storage Implementation", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5013765" }, } ], "_recordsReturned": 25 }
Example: Using the REST API to Get
Clarity
Data in Excel
Using the same parameters from the table above, you can populate data in a spreadsheet application such as Microsoft Excel.
Follow these steps
:
  1. In Excel, click
    Data
    ,
    From Web
    .
  2. Click
    Advanced
    .
  3. In the
    URL parts
    field, enter your
    Clarity
    server URL and port number followed by
    /ppm/rest/v1/<object_class>
  4. Enter the following header parameters:
    1. Type
      Authorization
      and then type
      Bearer
      followed by one space and paste your API key from
      Clarity
      .
    2. Type
      x-api-ppm-client
      and then enter your integration application client ID from
      Clarity
      (it appeared above your key in the temporary
      New API Key
      pop-up page when you generated the key). Your administrator can also look up and send you the client ID; however, they cannot identify your key.
    3. Enter
      ContentType
      and then type
      application/json
  5. Click
    OK
    .
    image2019-6-6_10-13-48.png
  6. In the query editor, in the
    _results
    row, click
    List
    .
    image2019-6-6_10-36-3.png
  7. In the
    Convert
    menu, click
    To Table
    .
    image2019-6-6_10-38-42.png
  8. Click 
    Expand Columns
    .
    image2019-6-6_10-41-17.png
  9. Click
    Close and Load
    .
    image2019-6-6_10-23-31.png
You can repeat this example for other objects such as resources and tasks.
REST API Keys and SSO (On-Premise)
Some of the key points you need to remember while using API keys in an SSO environment are:
  •   You should make REST calls to
    Clarity
    by using the
    http://hostname:port/tokens/rest/v1
    request. The “/tokens” parameter works only in an SSO environment. When you use the “/tokens” parameter in an SSO environment,
    Clarity
    adds additional headers to force token-based authorization and then forwards the request to "/ppm/rest" thus allowing access to the same rest API endpoints.
  •   You need to create a new SSO policy to ensure that any request directed to the
    http://hostname:port/tokens/rest/v1
    endpoint is not protected. This will allow requests that use tokens to bypass SSO and enable users to be authenticated based on
    Clarity
    API keys.
  •   Unprotecting the
    http://hostname:port/ppm
    endpoint will not enable you to use REST APIs and API keys in an SSO environment.
REST API Keys and SSO (SaaS)
If you are using the
Clarity
SaaS environment, please open a support ticket to ensure the API Keys feature is enabled in your environment.
You do not need to open a support ticket to enable the API Keys feature if your environment is hosted on the Google Cloud Platform.