Agile Central - WSAPI: Api Key and Oauth Client FAQ

Document ID : KB000011568
Last Modified Date : 14/02/2018
Show Technical Document Details
Question:

Issue

Frequently Asked Questions about authentication methods provided by CA Agile Central Application Manager.

Answer:

 

Resolution

API KEY FAQ:

When was API Key functionality introduced?


It was mentioned in "What's New the week of April 14, 2014".

Does API Key work on-premises?

Api Keys are not supported on-premises. Only basic authentication (username/password) is supported. In addition to basic authentication, WS API POST/PUT/DELETErequests  also require security token that is valid per session.

Does API Key work on Sandbox?

Api Keys are not supported on sandbox.rallydev.com. See article "How to update an artifact in sandbox via WS API".

Can I use API Key instead of LoginKey?

API Keys cannot be used with legacy AppSDK1 apps.  AppSDK2 supports API Keys.
However if you use the LoginKey to display CA Agile Central Standard Reports inside AppSDK2 apps it will not work. See article "When using ApiKey with StandardReport a user is still required to authenticate".
For more information about LoginKey see this github repo and the article "LoginKey Troublshooting".

Can certain users be blocked from generating API Key?

No. There is an "API Keys enabled" flag under "Admin Capabilities" section on Subscription tab. It can be toggled by a subscription administrator. This flag disables or enables API Key functionality for the entire subscription. There is no finer granularity that allows a selective enabling and disabling of access to API Key generation by users, roles or permissions. Any user with valid permissions can create an API Key. An editor can create a read-only API Key, but a viewer cannot create an API Key that allows writing. 

How are revisions authenticated with API Key reflected in Revision History?

If a work item is modified via a script that is authenticated with ApiKey the Author of the Revision will point to the user whose ApiKey is used in the code. Revision History makes not distinction between revisions created by a user authenticated with username/password and revisions created by a user authenticated with API Key - both point to the same user account.

Do I  have to use a security token for POST and DELETE requests in addition to API Key?

No. Security token described here predates API Keys. For examples on how to use security token see this article: "How to create a defect with a browser's REST client".

API Keys are easier to use and is not limited to one HTTP session.

Here are examples of curl commands that use API Key:

create example:
curl --header "zsessionid:_myKey123" -H"Content-Type: application/json" -d"{\"Defect\":{\"Name\":\"bad defect\",\"ScheduleState\":\"Custom 1\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/Defect/create

update example:
curl --header "zsessionid:_myKey123" -H "Content-Type: application/json" -d"{\"Defect\":{\"Resolution\":\"Not a Defect\",\"State\":\"Fixed\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/Defect/777

delete example:
curl --header "zsessionid:_myKey123" -H "Content-Type: application/json" -X delete https://rally1.rallydev.com/slm/webservice/v2.0/Defect/777

See also article "How to use API Key with cURL".

Should I use ApiKey or security token?

On-premises instances of CA Agile Central and sandbox.rallydev.com have no choice but to use security token (in combination with username/password). ApiKey is not supported in those environments.
On rally1.rallydev.com we recommend using ApiKey. ApiKey is more reliable and easier to use. It has been designed to overcome the challenges the security token often presents.

Per WebServices API documentation, starting with WS API v2.0 all POST(PUT,DELETE) requests require not only basic authentication (username/password) but also a security token. In other words, a combination of username/password and a security token is required. Those security tokens expire with each HTTP session. Obviously the browser maintains a session for you, so this is not an issue when using a browser REST client. But if you are hitting WS API create, update or delete endpoints outside of the browser, e.g. using CURL command you need to maintain the session yourself via a cookie. Otherwise the GET request to this endpoint: https://rally1.rallydev.com/slm/webservice/v2.0/security/authorize and a POST request to create or update an artifact constitute two separate requests. Appending a token generated by the first request to the second request will result in "Invalid key" when HTTP session is not maintained by the user.

ApiKey is designed to remove those difficulties:

  • ApiKey does not expire when HTTP session expires.
  • ApiKey is used on its own. It is not used in combination with username/password or in combination with security token. There is no need to hit /security/authorize endpoint prior to making POST requests.


What CA Agile Central API toolkits support API Keys?

AppSDK2
CA Agile Central Rest Toolkit for Java,
CA Agile Central Rest Toolkit for Ruby,
rally-node,
pyral

Can I use ApiKey with a custom code where CA Agile Central API toolkits are not used?

Yes. For example, a java programmer may decide not to use a CA Agile Central toolkit and build a custom integration using org.apache.http.client. ApiKey may still be used for authentication by setting zsessionid header to it.

Does API Key work with SSO?

As of April 16, 2015 ApiKey works for users who exclusively authenticate via SSO. There is no longer a requirement to add api users to the exceptions list.

Here is an example that is using ApiKey in the environment that uses SSO. The user whose ApiKey is used is NOT on the SSO exceptions list.
To make sure that credentials are not cashed we log out entirely and start an incognito session in the browser. To confirm that credentials are not cached this WS API endpoint is pasted in the address bar of the browser: https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement.
A prompt to login comes up as expected:

User-added image

We cancel. Error 401 appears as expected. So far we confirmed that credentials are not cached.
Next we start a browser REST client. In this example it is Firefox Poster. The same endpoint is used in URL box, and zsessionid header is set to ApiKey. The screenshot below shows success. TotalResultCount of this query happened to be 45960:

User-added image

Does API Key continue working when the associated user's password expires?

When SSO is enabled the password policy in the subscription settings will be ignored (except for those users on the exceptions list as expected)

Note:  if the user gets disabled in Active Directory but their Rally account is still set to active - while they won’t be able to login via the UI their API key will continue to function.  The admins will need to make sure the Rally account is also disabled or explicitly remove the API key from the subscription

AUTHORIZED APPLICATION FAQ:

How is an authorized applications created (I don't see a create new option)?


The Authorized Applications section is referring to any CA Agile Central integrated application that has a 'Log in Using CA Agile Central' button. The best way to answer this question is with an example. The authorized application entry is created when you use the 'Login with CA Agile Central' button on any of the supported applications such as (Flowdock, Salesforce).

User-added image

Once you click on the 'Log in Using CA Agile Central' button it will create the entry under the Authorized Application tab under the CA Agile Central Application Manager (https://rally1.rallydev.com/login).


User-added image


This functionality allows you to login to these integrated external applications in a more simplified way (no need to input a separate username/password). The CA Agile Central data that is being accessed is the session tokens used to login. Flowdock will never know the actual CA Agile Central Username and password in order to allow access to Flowdock. By using the token it will allow the user to login to Flowdock. This also does not mean that Flowdock has full access to CA Agile Central. It is just for the means of authentication.

Do I need to have an API Key first to create an authorized application

No, API keys are not needed and are not related to authorized applications. API keys that are created by a CA Agile Central user just impersonates that user to have access to the CA Agile Central WSAPI without the need to enter username and password. API keys are used in custom apps that need access to the CA Agile Central WSAPI. Only an active CA Agile Central user can create an API key. Once the user is inactivated in CA Agile Central this will also revoke the API key.

Can inactive user authorize application?

Only an active user in CA Agile Central can give authorization to applications using CA Agile Central to login. Once the user is inactivated and no longer has access to their CA Agile Central account then this will also revoke the access to the authorized application immediately.

Additional Information:

RELATED ARTICLE:
Also see this article "Does ApiKey become disabled when a user is disabled?"