This page describes how to create and use the API Clients identity type to provide secure access to the Controller through AppDynamics Controller REST API calls. These calls use Open Authorization (OAuth) token-based authentication.

Follow these steps to create the API client and make calls to the AppDynamics REST APIs:

  1. Confirm that you have access permissions for creating API Clients.
  2. Create an API Client.

  3. Generate Access Tokens.

  4. Use the Access Token to make REST calls.

  5. Manage Access Tokens.

Access Permissions for Creating API Clients

To create API clients, you are required to be assigned to the role of an Account Owner or an Administer. You can view the API Client settings in the Settings > Administration page of the Controller.

Create API Clients

You can create new API Client identity types that can be used to generate OAuth tokens.

  1. Log in to the Controller UI as an Account Owner or other roles with the Administer users, groups, roles ... permission.
  2. Click  > Administration.
  3. Click the API Clients tab to view the list of existing clients.
  4. Click + Create.
  5. Enter the Client Name and Description.

  6. Click Generate Secret to populate the Client Secret. 
    This will generate a UUID as the secret of the API Client. 

    This API Client secret acts as a password. It does not generate the authentication token.

  7. Set the Default API-generated Token Expiration. This expiration only applies to authentication tokens generated through the /controller/api/oauth/access_token REST API, not to Temporary Access Tokens generated from the UI. See Using the Access Token.

    Every API-generated access token has an expiration. Although the default is five minutes, you can set it to any second, minute, or hour limit. The Default API-generated Token has a shorter expiration than the authentication token generated through the Administration UI.

  8. Add the Roles you would like to associate with this API Client. You can add or remove roles at any time. See Manage Custom Roles for Cisco AppDynamics.

    The REST APIs will use the identity which the access token represents to pull up RBAC permissions and check those permissions at the underlying API level.

  9. Click Save at the top right.

Generate Access Tokens 

You can generate access token for each API access call into your Controller by generating the token through one of the following means:

  • Administration UI: These tokens usually have a longer expiration. The account administrator can generate and distribute to parties/teams who need Controller access, but do not want to generate tokens frequently. 
  • OAuth API: These tokens usually have a relatively short expiration. The program generates and refreshes regularly before expiration. These tokens are visible from the UI and are not individually tracked and managed.

Generate the Token Through the Administration UI 

You can generate the access token by navigating to Administration > API Clients and clicking Generate Temporary Access Token:


Generate the Token Through the OAuth API 

You can use REST APIs to generate a short-lived access token. This default, on-demand token is not tracked on the UI. 

Use the OAuth 2.0 Client Credentials Grant to request access tokens with the AppDynamics OAuth API.

For example, use POST with the OAuth API endpoint /controller/api/oauth/access_token. You will need the API Client name, the Client Secret, and to specify grant_type=client_credentials to generate the token. The Content-Type header is not restricted to application/x-www-form-urlencoded, but is correct in the given example because of the data being passed in the request body. Note also that the default Content-Type being returned from this example call will be application/vnd.appd.cntrl+json;v=1.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" "https://<controller address>/controller/api/oauth/access_token" -d 'grant_type=client_credentials&client_id=<apiClientName>@<accountName>&client_secret=<clientSecret>'
BASH

Example Call and Response

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -u 'testclient:face10d5-573e-4a75-8396-afa006fd8f19' \
"https://<controller address>/controller/api/oauth/access_token" \
-d 'grant_type=client_credentials&client_id=testclient@<accountName>&client_secret=face10d5-573e-4a75-8396-afa006fd8f19'
BASH 
{
"access_token": "eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImV4cCI6MTUzNjI3MjI1NiwianRpIjoiT2twZHVDdmduSDdwMmduMnc4MFRtQSIsImlhdCI6MTUzNjI3MTk1NiwibmJmIjoxNTM2MjcxODM2LCJzdWIiOiJUZXN0QXBpQ2xpZW50IiwidHlwZSI6IkFQSV9DTElFTlQiLCJpZCI6ImFmZTQxMzg5LTJlNjMtNDQyYS1hY2U2LTEyYzU5NGFlOGM2OCIsImFjY3RJZCI6IjhlMGQ3NjI1LTY4YzEtNDE4Mi1hMmFmLWFhMTY1MzllZDg0OCIsImFjY3ROYW1lIjoiZTJlLWN1c3RvbWVyIn0.95EyDNV5muTN_4zGOXIPQQHOdVDSiEynKSgk08UHlh0",
"expires_in": 300
}
CODE

Use the Access Token to Make REST Calls

You can use the access token with the Authorization header to make calls to the AppDynamics REST APIs. The access token can be gotten from the Administration UI or through the OAuth API.

  1. Copy and paste the access token into the Header of your curl command. This example uses the generated token with the /applications  endpoint to list all applications: 

    curl --location --request GET 'https://<controller address>/controller/rest/applications' \
--header 'Authorization: Bearer eyJraWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBcHBEeW5hbWljcyIsImF1ZCI6IkFwcERfQVBJcyIsImp0aSI6IjlybDVyU0tWZDZwN3hKM3A5NWRfemciLCJzdWIiOiJwb3N0bWFuIiwiaWRUeXBlIjoiQVBJX0NMSUVOVCIsImlkIjoiNjgzZmZmODMtNTY5YS00OGRkLWE4MjMtYWE0ODA4NGYzN2UxIiwiYWNjdElkIjoiYTllMjEzNjQtZWE3Ny00NzllLTk3ZmYtZWJiZDI3NjYzZmJlIiwidG50SWQiOiJhOWUyMTM2NC1lYTc3LTQ3OWUtOTdmZi1lYmJkMjc2NjNmYmUiLCJhY2N0TmFtZSI6ImFwcGR5bmFtaWNzIiwidGVuYW50TmFtZSI6ImFwcGR5bmFtaWNzIiwiZm1tVG50SWQiOm51bGwsImFjY3RQZXJtIjpbXSwicm9sZUlkcyI6W10sImlhdCI6MTY1OTQ4Njk1NiwibmJmIjoxNjU5NDg2ODM2LCJleHAiOjE2NTk1NzMzNTYsInRva2VuVHlwZSI6IkFDQ0VTUyJ9.sKG2hkFofWK9avqr7RlzVEM_APiCUiXRXmA7qm12Wr4'
    BASH

  2. Check that your call is successful. It should look like this and return all applications:  

    <applications>
  <application>
    <id>25</id>
    <name>My Test App</name>
    <description></description>
    <accountGuid>a9e21364-ea77-479e-97ff-xxxxxxxxxxxxx</accountGuid>
  </application>
  <application>
    <id>54</id>
    <name>E-Commerce App</name>
    <accountGuid>a9e21364-ea77-479e-97ff-zzzzzzzzzzzzz</accountGuid>
  </application>
</applications>
    XML


  3. In the case of failure: HTTP 401 Unauthorized "Failed to authenticate: invalid access token." is returned.

Manage Access Tokens 

Access tokens are based on JWT, therefore decoding them will not show sensitive information. 

However, if you believe that your token has become compromised, you can revoke it by clicking Revoke or by deleting the API Client to invalidate the token. Calls using revoked access tokens fail to authenticate with a 401 Unauthorized error HTTP status code. You can go to Administration > API Clients  and click Regenerate to refresh a token:

Regenerated tokens do not disable older tokens. The older tokens will remain active until they expire.

When you regenerate a token, you can set the Temporary Token Expiration.

There is no way to retrieve previous or currently valid tokens. Therefore, only the current token can be revoked.

Also, API-generated tokens that have Default API-generated Token Expiration, cannot be viewed nor revoked through the UI or REST API.

Open Authorization (OAuth) Mechanisms

OAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications. See https://oauth.net/.

It acts as the intermediary on your behalf by providing third-party applications with an access token that authorizes sharing specific account information. Using the OAuth protocol with AppDynamics Controller REST APIs is the best way to securely grant access to your Controller information.

The OAuth authentication process authenticates a request token and uses it to obtain an encrypted access token from your Controller. Once the access token is available, you can use it to make requests to your Controller until the token expires or is revoked.

The tokens are based on JSON Web Tokens (JWT) authentication format, which is the industry standard RFC 7519 method for representing claims securely between two parties.