AppDynamics Application Principal Management Service API

Get Started

Cisco AppDynamics exposes various APIs for customizing and extending its features.

Base URI

Every API request begins with this Base URI:

Code Snippet

Copyhttps://{tenantName}.observe.appdynamics.com/

Servers Code Snippet

Code Snippet

Copyhttps://{tenantName}.observe.appdynamics.com/administration/v1beta/

Authentication

NOTE: Cisco AppDynamics does not support using agent clients outside of the context of supported monitoring agents.

Token requests adhere to a standard OAuth2 request format. The authentication method you select when creating the agent principal determines the grant type for supplying the client credentials in the token request. For client configurations with client_secret_basic, the client credentials are sent in the basic authorization header.

For example:

command

Copycurl -X "POST" "https://{tenantName}.observe.appdynamics.com/auth/{tenantId}/default/oauth2/token" \
     -H 'Content-Type: agent/x-www-form-urlencoded; charset=utf-8' \
     -u 'c3ififj4fj9i043j09f:uGRslp1GbrOKAvMmr5vWGQFfji399hjfFE13sfL' \
     --data-urlencode "grant_type=client_credentials"

If the client is configured with client_secret_post, the client credentials will be sent in the request body. For example:

command

Copycurl -X "POST" "https://{tenantName}.observe.appdynamics.com/auth/{tenantId}/default/oauth2/token" \
     -H 'Content-Type: agent/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "client_id=c3ififj4fj9i043j09f" \
     --data-urlencode "client_secret=uGRslp1GbrOKAvMmr5vWGQFfji399hjfFE13sfL"

Any method you use to pass the credentials returns a standard OAuth2 token response. For example:

json

Copy{
  "access_token": "{JWT accessToken}",
  "expires_in": 3599,
  "scope": "introspect_tokens revoke_tokens",
  "token_type": "bearer"
}

You can use the returned access token in requests to permitted APIs in the authorization header as a Bearer type. For example:

command

Copycurl "https://{tenantName}.observe.appdynamics.com/{someAPI}" \
     -H 'Authorization: Bearer {accessToken}'

Create an Agent

The following curl command uses HTTP POST with the {accessToken} that you received in the Authentication step to create a new agent with the dislpay name "My API Client!":

command

Copycurl -X "POST" "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents" \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"authType": "client_secret_basic",
"description": "My API Client!",
"displayName": "My Test Agent"
}'

The JSON response from the call will look similar to this:

json

Copy{
  "id": "c0e3beb9-9822-4311-ab87-6525df16b5f3",
  "clientSecret": "ihdmaL28bVJeqad1",
  "authType": "client_secret_basic",
  "description": "My API Client!",
  "displayName": "My Test Agent",
  "createdAt": "2022-07-08T21:20:39.000Z",
  "updatedAt": "2022-07-08T21:20:39.000Z"
}

Get an Agent

You can fetch an agent using HTTP GET with the following endpoint, where {clientId} is the ID of the agent:

Code Snippet

Copyhttps://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents/{clientId}

For example, the following curl call returns the agent with the ID 0e3beb9-9822-4311-ab87-6525df16b5f3 that we just created:

command

Copycurl -X "GET" "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents/0e3beb9-9822-4311-ab87-6525df16b5f3" \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json; charset=utf-8'

The JSON response will look very similar to the one you received when creating an agent:

json

Copy{ 
  "id" : "c3mfi429i0f320j90fj9d", 
  "description": "My API Client!",
  "displayName": "My Test Agent",
  "authType": "client_secret_basic", 
  "hasRotatedSecrets": true, 
  "createdAt": "2021-06-30T20:05:32.000Z",
  "updatedAt": "2021-06-30T20:05:32.000Z" 
}

List Agents

You can also request a list of all your agents with HTTP GET on the following endpoint:

Code Snippet

Copyhttps://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents

This curl command fetch a list of your agents:

Code Snippet

Copycurl "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents" \
     -H 'Authorization: Bearer {accessToken}'

The returned JSON response specifies the number of agents, 3 in this example, and objects representing each agent:

json

Copy{
  "total": 3,
  "items": [
    {
      "id": "c3ififj4fj9i043j09f",
      "displayName": "Infra Agent 1",
      "description": "This is an infra agent.",
      "authType": "client_secret_basic",
      "createdAt": "2021-07-08T18:01:16.000Z",
      "updatedAt": "2021-07-08T18:01:16.000Z"
    },
    {
      "id": "c3k9f0024jk90f4290j",
      "displayName": "My Test Agent 1",
      "description": "This is an open telemetry collector.",
      "authType": "client_secret_basic",
      "createdAt": "2021-06-30T20:03:11.000Z",
      "updatedAt": "2021-07-19T18:31:45.027Z"
    },
    {
      "id": "c390fj3490ijc9i34d3",
      "displayName": "My Test Agent 2",
      "description": "This agent uses post credentials.",
      "authType": "client_secret_post",
      "createdAt": "2021-06-30T20:03:21.000Z",
      "updatedAt": "2021-06-30T20:03:21.000Z"
    }
  ]
}

List Agents with Filtering

NOTE: Cisco AppDynamics uses the System for Cross-domain Identity Management (SCIM) format for filtering agents. The SCIM protocol is an application-level REST protocol that manages the identity data between multiple applications.

When requesting a list of agents, you can pass the query string parameter filter with one of the properties of the agent objects. For example, you could filter on the agent property displayName as shown in the below curl example:

command

Copycurl "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents?filter=displayName%20Infra%20Agent%201" \
     -H 'Authorization: Bearer {accessToken}'

The response will return the agent matching the filter's criteria:

json

Copy{
  "total": 1,
  "items": [
    {
      "id": "c3ififj4fj9i043j09f",
      "displayName": "Infra Agent 1",
      "description": "This is an infra agent.",
      "authType": "client_secret_basic",
      "createdAt": "2021-07-08T18:01:16.000Z",
      "updatedAt": "2021-07-08T18:01:16.000Z"
    }
  ]
}

Update an Agent

To update an agent, you use the same endpoint to fetch an agent except with HTTP PUT and with a request body with the properties and the updated values.

In this curl example, the fields displayName and description are being updated for the agent:

command

Copycurl -X "PUT" "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents/{clientId}" \
     -H 'Authorization: Bearer {accessToken}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "authType": "client_secret_post",
  "displayName": "My Test Agent 1",
  "description": "This is an open telemetry collector, but with new text."
}'

The JSON response reflects the update you requested with the createdAt and updatedAt dates and times.

json

Copy{
  "id": "c3k9f0024jk90f4290j",
  "displayName": "My Test Agent 1",
  "description": "This is an open telemetry collector, but with new text.",
  "authType": "client_secret_post",
  "createdAt": "2021-06-30T20:03:11.000Z",
  "updatedAt": "2021-07-19T18:31:45.027Z"
}

Delete an Agent

You use HTTP DELETE with the same endpoint for fetching and updating one agent as shown below:

command

Copycurl -X "DELETE" "https://{tenantName}.observe.appdynamics.com/administration/v1beta/clients/agents/{clientId}" \
     -H 'Authorization: Bearer {accessToken}'