Agile Central: SDK Apps - Why despite using api key we are prompted to log into Agile Central by our externally deployed app?

Document ID : KB000100436
Last Modified Date : 09/06/2018
Show Technical Document Details
We followed the documentation, developed an SDK app, deployed it externally and appended an Api Key. The app is loading well, but any subsequent action within the app, any click on any object - results in a Agile Central login screen.

Here is what it looks like:
The first screen shot is showing our external app running on our own web server appended with the apiKey.
Then, we click on any of the Features (in the ID) column and that leads us to a login screen. See below.

When this app runs on the dashboard on on a custom HTML page then we are not getting the login screen and we can click on the Feature ID and see it.

Why are we getting the login screen only with the external app, are we missing anything?

User-added image

User-added image

The short answer to this question is:
"You are doing nothing wrong. This is the expected behavior. Externally deployed apps are not meant for interaction with Agile Central. Clicking on objects will bring up the login screen".

To explain it thoroughly we need to take a step back and explain a few Agile Central's concepts, review the SDK architecture and understand what developing apps externally means technically. This will help us understand the limitations of external apps and how to best use them.

1. Session Token.
Session Token is a value that's generated by Agile Central's application server. It is generated when a username logs into the application. The session token allows its holder to act inside Agile Central in accordance with that user's permissions. The session token expires when the user is logging out. A session token is required to allow continuous activity with Agile Central.

2. Api Key.
Api Key is a key that uniquely belongs to its user. It allows the user to authenticate and authorize to Agile Central instead of providing the username/password credentials. It does not expire, but it will only work if the user is enabled. If the user is Locked or Disabled then it won't work. As long as the user is enabled then it will work even if the password keeps changing. It is a 'thumb print' that's unique to the user. Api Keys are normally used by integration programs into Agile Central. The advantage is that the credentials aren't kept on the remote machines and that the api key won't expire. It enables the integration program treat the Api Key as a 'Service Account'. Api Keys will many times be Read-Only in order to limit the possibility of undesirable updates or abuse. 
Api Key is not a Session Token. Using an Api Key does not create a session within Agile Central. Api Keys are normally to perform REST calls to Agile's Endpoint using WSAPI. They must be provided to any subsequent call to the same or another Endpoint.
More on Api Keys: 
More on WSAPI:

3. Agile Central's JavaScript App SDK.
The SDK is a javascript library that allows you to develop apps for Agile Central. The SDK classes include much of the Agile Central's look, feel and behavior as you experience when using the user interface. It includes the same grids, trees, buttons, filter widgets, grid menu options (including for bulk operations), coloring, style-sheets and more. Much of the default behavior that you see and experience in Agile Central is integral built-in part of the SDK. 
More on the App SDK:

4. Extending Agile Central.
Agile Central offers a natural way to extend its functionality and behavior. This way is the Agile Central apps. The apps can be included on users' dashboards or on shared custom HTML pages. You can share them across your teams. The apps are provided a separate execution space to run. This design separates the core functionality of Agile Central from its extensions (the apps). Being a SaaS product Agile Central frequently deploys fixes, betas and other core functions. It is critical to separate the product core from the extensions. This allows the the extensions (app, custom pages) to not be impacted by the core frequent deployments, and also allows the core product not to be impacted with updates or problems with the apps. 

When you identify a gap, perhaps missing or incomplete behavior you may consider developing an app to fill in the missing function. This may be a simple or complex task, depending on the gap and your requirement. An example of a simple gap could be to extend an already existing app so that it works with additional artifacts. A more complex requirement may be if you would like to display a chart that's based on complex calculations (that will have to be part of your app). 
You will use the SDK to develop your apps using javascript. While you can always build from scratch, it's a good practice to find similar apps and reuse parts of their code. Agile Central's apps are open source (kept in public repositories in Git Hub), you can download them and modify the code to essentially develop your own app. You will normally use the Rally App Builder to create, build, test and deploy your code. The 'Additional Information' section below has the references to the repositories.

The SDK-based apps live and operate in the context of Agile Central's user interface. They require a Session Token to operate. These apps are hosted in pages inside Agile Central. They 'participate' in the same session the user already has open. The user will authenticate and log into Agile Central, then that Session Token is shared between the core pages, the apps and custom HTML pages. All live under the same Agile Central's session context. 

Let's examine what this actually means: 
Consider an that lists User Stories where clicking a Story's name will open another frame to display its details. The session token allows the smooth operation between your browser and the application server so the screens can change without requesting you to login every time. This is what enables the experience of continuous interaction for both the core product and the apps.

5. Accessing and interacting with yours app.
We covered accessing your app when they are part of Agile Central itself. But,
Customers may want to access the apps "externally", maybe from a corporate portal for example. "Externally" means that you are not logged into Agile Central when accessing the app.

Can it be done?   Let's elaborate.

There are two ways to do that, each with implications and constraints. Let's examine these ways.

Custom HTML Page
a. You can share your app on a Custom HTML page in Agile Central. Your app is given a unique HTML page with a unique URL. To find the URL of your page, visit your page, then look at your browser address bar. It will look like:
User-added image

You can invoke this page from anywhere - But:
i. Since it's part of Agile Central then you will be prompted to login. If your browser has another tab open that's already logged on then your page will share the session token and be 'already logged in'.

ii. Once you call that page you will see the full menu bar of Agile Central (as you actually are in Agile Central). There is nothing preventing you from start navigating Agile Central , browse to any page, click every button etc.

iii. There is an option to append an 'expandApp' argument to the page URL, that will display your app expanded. Still, you will be able to click User-added image this button and get back to a non-expanded mode so you again can navigate Agile Central.

Custom HTML pages can not be made to display your app stand-alone. It can not be made exclusive on the browser window or frame. 

Develop Apps Externally
b. You can "develop and deploy your app externally". 
To achieve exclusivity , that is displaying your app and only your app on the browser's frame, and even to embed it to your own corporate portal's page, you will need to deploy your app 'externally'. 

See on External development:!/guide/developing_externally
See on Embedding your app:!/guide/embedding_apps-section-develop-the-app

There are a few things to explain about this concept. It also comes with its limitations:

i. You will run your app in a different web server. It is not part of Agile Central at all. Your app's execution is stand-alone and exclusive to your page.

ii. You append the Api Key to your app's HTML page URL. Your app's entry page will be displayed.

iii. Further clicks in your app to bring up additional information from Agile Central will land you on the login screen.
Let's examine again an app such as what we examined earlier, a list of User Stories where clicking the Story's name shall display the details in another frame:

Using the External/Embedding method you will get to the app's entry screen (the list of User Stories), but clicking on the stories name will get you to Agile Central's login screen. It will not display the story's details.

This is because:
No Session Token was ever created.

The Api Key got you passed for the call to the entry page. The SDK isn't 'keeping it' to reuse for any next calls of your app. Since no other session token on your browser then you're landing on the login page. The SDK is designed to work inside Agile Central and share/participate with the browser/app-server session token. As we explained the SDK is intended to extend the Agile Central app. It is not designed to allow for continuous interaction on an external server.  

Externally deployed apps therefore are not meant for continuous interaction with Agile Central. They should be used mainly for information that is read-only in nature and not interactive, such as charts, graphs or reports. Apps such as Burnup, Burndown Charts are good examples for apps that can and should be deployed externally and embedded on your corporate pages.

Let us summarize
We started by asking why clicking any object in an externally embedded app results in a login screen to Agile Central.
The answer is because external/embedded apps can only display information. Further interaction will require a login.

- The SDK is a library that is designed to extend Agile Central's user interface and application experience. It can not interact with Agile's back-end on its own, it must do that through a session token.

- Api Key can allow a 'poke' one-time call into Agile Central. They do not hold a session for a continuous interaction. When integrations or WSAPI based calls are made they must provide the Api Key with every call to each REST Endpoint. Each call is a one-time transaction. 

- As such, you can append the Api Key to your call of your external/embedded SDK based app and be able to 'poke' for Agile Central data. The SDK can not re-use the Key. External apps are best to display read-only data such as Charts or Reports.

Additional Information:
A deeper explanation on "Service Accounts" and Password Expiration, see:

A deeper explanation on Read-Only Api Keys, see:

Agile Central's Core Apps repository:
Agile Central's Community Apps repository: