Agile Central: WSAPI - Why should we generate a Read Only API Key?

Document ID : KB000098242
Last Modified Date : 28/05/2018
Show Technical Document Details
Introduction:
API Keys are strings that authenticate a user when accessing the CA Agile Central Web Services API. They do not expire and can be used instead of conventional credentials. More on API Keys can be found at: https://help.rallydev.com/external-api-keys
Background:
The following article explains how you create an API Key:
https://comm.support.ca.com/kb/how-to-create-an-api-key-for-agile-central/kb000010814
Instructions:
When creating or modifying an API Key, you have two options:  Read-Only vs. Full-Access key.
What is the difference and what is the purpose of these two types of keys?

User-added image

In order to appreciate the two types of keys, you need to consider their purpose. The purpose of an API Key is to serve as alternative to the credentials of a certain username. In addition the key will not expire.

The purpose of the key is to allow a username to securely connect and act within CA Agile Central remotely. Often, API Keys will be used by client programs who integrate with Agile Central. When providing your key to such programs you need to consider what this program needs to do, what actions it needs to take and you need to make every effort to minimize the level of risk that can be done in any of the following circumstances:

- Your key is hijacked or stolen.
- The client software has code problems resulting in wrong updates within Agile Central.

If your key has Full-Access then such situations may result in harmful updates to Agile Central on behalf of your username.

Therefore, a more secure practice is for you to generate a Read-Only key and share that key with the client software. A Read-Only key is only able to extract information from Agile Central, but not make any updates. In terms of WSAPI: It can only use the Read endpoints (via the http/s GET method) , but has no access to the Create/Copy/Delete/Update endpoints.

A natural question will be:  So, what should we do if the client software also needs to update Agile Central with some information?

The best and most secure practice in this situation will not be for you to generate and share a Full-Access Key. It will be best to share two keys with the app, one for Read-Only, the other for Full-Access. The client app may want to use the Read-Only key for its reads and the Full-Access key for its updates. If possible, an even better approach for the client app is to make a Read phase and perform all the readings using the Read-Only key, then make an Update phase where making all the updates using the Full-Access key. This may not always be possible, but a good design will take all that into account. If the client app is developed with such two phases then it can take even more secure measures when performing the second Update phase.

The two (Read-Only and Full-Access) keys may be of the same username or not. In essence you may want to allow the app the minimal access required to perform what it needs. When giving away the key/keys to your app/s you may want to consider tracking its updates within Agile Central. The Revision History is normally a place where you can find what updates took place to the artifacts and on who's behalf. You may want to provide a key to a username that you will then more easily track.


To Summarize:
API Keys are essentially usernames who are used by client programs. You need to be preemptive about securing their access and minimizing potential harm they may cause. A Read-Only key is allowing you an extra security measure to prevent harmful updates within Agile Central. Some apps will only read information - provide them only with a Read-Only key. For those apps who need to make updates into Agile Central: consider splitting them to two apps or two phases for Read , then Write. The Write phase/app will require a Full-Access key, but it can be of a different (possibly designated) username.