Getting Started

In this getting started guide, we will show you how to obtain access tokens for authentication, make calls to the Access Management API, and then introduce some URI endpoints that you'll use to perform common tasks. The examples will use cURL calls from the command line and show you JSON responses. By the end of this mini tutorial, you should be familiar with the Access Management APIs and be ready to use them with your Cisco Observability Platform solutions.

Standard REST methods are supported on the API, which include POST, GET, and DELETE operations through HTTPS. All payloads to and from the REST interface must be in JSON format. Below is high-level description of the API resources:

Roles - Represent a set of permissions that can be assigned to a Principal.

• View a List of All the Roles for a Tenant
• Create a Custom Role
• Get a Role
• Update a Role

Permissions - Represent the privileges or access to resources.

• Get the Permissions of a Role
• Add and Remove Permissions from a Role

Principals - Represent an Agent, a User, or a Service.

• Update Roles for a Principal
• Retrieve the Roles for a Principal

Base URI

Every API request will begin with the following Base URI. You can find your tenant name from the Accounts Management Portal for the value to replace {tenant-name}.

https://{tenant-name}.observe.appdynamics.com/iam/policy-admin/v1beta2

1. Authentication

You must obtain the access token to access the Knowledge Store API. See Authenticate and Authorize Calls to the Access Management API.

2. View a List of All the Roles for a Tenant

You can view all the roles for a tenant using HTTP GET in the following request:

curl -X GET 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

HTTP Status Codes

Example Response Body

{
    "total": 21,
    "items": [
        {
            "id": "iam:tenantAdmin",
            "layerId": "iam",
            "layerType": "SOLUTION",
            "data": {
                "name": "tenantAdmin",
                "displayName": "Tenant Admin",
                "permissions": [
                    {
                        "id": "healthruleapiservice:getHealthForEntities"
                    },
                    "...",
                    {
                        "id": "healthruleapiservice:createHealthRuleV2"
                    }
                ],
                "description": "Can Access All APIs and Objects for a tenant",
                "scopes": [
                    "TENANT"
                ]
            }
        },
        "..."
    ]
}

3. Create a Custom Role

Create a (custom) role. Role name and permissions are part of the request:

curl -X POST https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken} \
 -d '{
        "name": "tenantSupportRole",
        "displayName": "Tenant Support Role",
        "description": "Read-only role for support users on the tenant"
}'

Response

HTTP Status Codes

Example Response Body

No response is returned.

4. Get a Role

Finally, retrieve one role out of the list that you fetched in step 2.

You'll need to first get all the views for the Tenant and look for tenantSupportRole in the response:

{
    "total": 21,
    "items": [
        "...",
        {
            "id": "18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole",
            "layerId": "18fd83f6-e513-4cd6-9054-022fe48bb833",
            "layerType": "TENANT",
            "data": {
                "name": "tenantSupportRole",
                "displayName": "Tenant Support Role",
                "permissions": [],
                "description": "Read-only role for support users on the tenant",
                "scopes": [
                    "TENANT"
                ]
            }
        },
        "..."
    ]
}

With the value for id (for example, 18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole), you can make the following call to fetch information about the role:

curl -X GET 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles/18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'

Response

HTTP Status Codes

Example Response Body

{
    "total": 21,
    "items": [
        "...",
        {
            "id": "18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole",
            "layerId": "18fd83f6-e513-4cd6-9054-022fe48bb833",
            "layerType": "TENANT",
            "data": {
                "name": "tenantSupportRole",
                "displayName": "Tenant Support Role",
                "permissions": [],
                "description": "Read-only role for support users on the tenant",
                "scopes": [
                    "TENANT"
                ]
            }
        },
        "..."
    ]
}

5. Update a Role

You can also use the API to update the role. Let's use the role we just fetched and update it with a new permission to read metric data.

curl -X PUT https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles/18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken} \
 -d '{
       "name": "tenantSupportRole",
       "displayName": "Tenant Support Role",
       "description": "Read-only role for support users on the tenant",
       "permissions": [
         {
            "id": "metrics:canReadData"
         }
       ]
}'

Response

HTTP Status Codes

Example Response Body

{
    "id": "18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole",
    "layerId": "18fd83f6-e513-4cd6-9054-022fe48bb833",
    "layerType": "TENANT",
    "data": {
        "name": "tenantSupportRole",
        "displayName": "Tenant Support Role",
        "permissions": [
           {
              "id": "metrics:canReadData",
              "name": "metrics:canReadData"
           }
        ],
        "description": "Read-only role for support users on the tenant",
        "scopes": [
            "TENANT"
        ]
    }
}

6. Get the Permissions of a Role

Get the permissions for the retrieved role specified by {roleId}:

curl -X GET 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles/{roleId}/permissions' \
--header 'Content-Type: application/json' \
--header 'Authorization:{accessToken}'

Response

HTTP Status Codes

Example Response Body

{
    "id": "18fd83f6-e513-4cd6-9054-022fe48bb833:tenantSupportRole",
    "layerId": "18fd83f6-e513-4cd6-9054-022fe48bb833",
    "layerType": "TENANT",
    "data": {
        "name": "tenantSupportRole",
        "displayName": "Tenant Support Role",
        "permissions": [],
        "description": "Read-only role for support users on the tenant",
        "scopes": [
            "TENANT"
        ]
    }
}

7. Update Roles for a Principal

A principal can be a user or service. You can fetch a list of user or service principals with the AppDynamics Application Principal Management Service API and then add or remove roles for one of the principals.

1. Fetch a list of the service principals with GET /clients/services or get users from the Account Management Portal. See the Application Principal Management Service API documentation to fetch the service principals and Manage User Accounts to get user principals. You'll need to be an Administrator to access user information.

2. Update the roles for one of the returned principals with PATCH /principals/roles. In this example, we add the role iam:configManager and remove the role iam:troubleshooter for the principal alice@mailinator.com of principal of type USER.

   curl -X PATCH 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/principals/roles' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {accessToken}' \
   --data-raw '{
       "principal": {
           "id": "alice@mailinator.com",
           "type": "USER"
       },
       "roles": {
           "iam:configManager": true,
           "iam:troubleshooter": null
       }
   }'
   

Response

HTTP Status Codes

Example Response Body

No response is returned.

8. Retrieve the Roles for a Principal

Retrieve the roles for a principal (user or server) by specifying the principal in the request body with the id field:

curl -X POST 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/principals/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--data-raw '{
    "id" : "<username>@<domain>"
}'

Response

HTTP Status Codes

Example Response Body

{
  "total": 1,
  "items": [
    {
      "id": "<username>@<domain>",
      "layerId": "<layer-id>",
      "layerType": "<layer-type>",
      "data": {
        "displayName": "Troubleshooter",
        "name": "trouble-shooter",
        "permissions": [
          {
            "id": "dashboard.read_dashboard",
            "name": "dashboard.read_dashboard"
          }
        ]
      }
    }
  ]
}

9. Add and Remove Principals from a Role

You add and remove principals from a role with the HTTP PATCH method, specifying the role to be updated in the URL path, and sending a request body with the principals to add or remove.

The following request adds the principal <username1>@<domain> to and removes the principal <username2>@<domain> from the role identified by {roleId}:

curl -X PATCH https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles/{roleId}/principals \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}'
--data-raw '{
  "principals": {
    "<username1>@<domain>": true,
     "<username2>@<domain>": false
  }
}'

Response

HTTP Status Codes

Example Response Body

No response is returned.

10. Delete a Custom Role

You use HTTP DELETE and specify the role you want to delete in the URL path.

The following call deletes the role from the Tenant specified by {roleId}:

curl -X DELETE 'https://{tenantName}.observe.appdynamics.com/iam/policy-admin/v1beta2/roles/{roleId}' \
--header 'Content-Type: application/json' \
--header 'Authorization:{accessToken}' 

Response

HTTP Status Codes

Example Response Body

No response is returned.

11. Try It Out Using Postman Collections

Prefer to use Postman rather than code or the command line? Check out our Postman Collections.