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

ccppmop157
In Clarity PPM 15.7, you can configure the REST API key authentication features to enable business users to integrate data between the 
Clarity PPM
 
New User Experience
 and other client applications. Integration architectures can allow users to authenticate through the REST API and accomplish certain Clarity PPM 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 PPM project data personalized for the current user. For project managers, third-party integration could read and update resource allocation data in Clarity PPM based on external application triggers such as other users updating a JIRA Kanban board.
 
2
 
 
REST API Key Support
This feature was available as BETA functionality and requires Release 15.6.1. It is supported in Clarity PPM 15.7.
REST API Prerequisites
 
API Administrators, Architects, and Lead Developers
: Contact your Clarity PPM application administrator for the following rights to configure the REST API feature and define clients in the New User Experience Administration menu:
  •  
    Administration - Access
     
  •  
    Administration - Authorization 
     
  •  
    API - Access
     
     
    Administration - Authorization
     is the same right for managing resources in the Classic PPM 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 Classic PPM, 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 the 
    Clarity PPM
     
    New User Experience
    .
  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 
Clarity PPM
 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 the 
    Clarity PPM
     
    New User Experience
    .
  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 PPM 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 PPM; 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 PPM 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 PPM 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 PPM 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 the 
    Clarity PPM
     
    New User Experience
    .
  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 PPM 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 PPM 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 PPM 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 PPM 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 PPM 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 PPM.
    2. Type 
      x-api-ppm-client
       and then enter your integration application client ID from Clarity PPM (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 PPM 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 PPM 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 PPM 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 PPM SaaS environment, please open a support ticket to ensure the API Keys feature is enabled in your environment.