Manage Environments - Environments

Manage Environments

Article Summary

Share feedback

Thanks for sharing your feedback!

The following Britive API methods help you to manage operations related to environments.

1. Details of an Environment

The GET method fetches the details of all environments present in the system.

GET	{{url}}/api/apps/{{appID}}/environments

Request Example

An example GET request for retrieving environments details is shown here:

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving environments details is shown here:

Status: 200 OK

[
  {
    "appContainerId": "10YwwR1V2aFt2UDtbjqJ",
    "environmentId": "1111",
    "environmentName": "Sigma"
  },
  {
    "appContainerId": "10YwwR1V2aFt2UDtbjqJ",
    "environmentId": "2222",
    "environmentName": "Sigma L"
  }
]

2. Details of Environment Groups and Environments

The GET method returns all the environment groups and the environments for the specified application.

GET	{{url}}/api/apps/{{appID}}/root-environment-group

Request Example

An example GET request for retrieving the environment groups and the environments for an application is shown here.

curl --location --request GET '{{url}}/api/apps/{{appID}}/root-environment-group' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example

An example response of the GET request for retrieving the environment groups and the environments for an application is shown here.

Status: 200 OK

{
    "environmentGroups": [
        {
            "name": "Root",
            "description": null,
            "id": "r-pak3",
            "parentId": "",
            "nativeId": "r-pak3",
            "nativeParentId": "",
            "childGroupIds": [
                "ou-pak3-c285231b",
                "ou-pak3-mu16yp7u",
                "ou-pak3-w3f3snyz",
                "ou-pak3-btmohrkz"
            ],
            "childEnvironmentIds": [
                "1111"
            ],
            "type": "Organization",
            "internalParentId": ""
        }
    ],
    "environments": [
        {
            "id": "1111",
            "name": "Dev Account 1",
            "description": null,
            "parentGroupId": "ou-pak3-c285231b",
            "type": "AWSAccount",
            "internalParentId": "",
            "status": "active"
        }
    ]
}

3. Create an Environment Group

The POST method creates an environment group within an application for the following applications: AWS Standalone, SalesForce, and ServiceNow.

Request Parameters

The following parameters are possible in the request:

Parameter	Description
name	Name of the environment group.
description	An optional description for the group.
type	The environment type is "group".
parentId	The ID of the parent under which the environment group has to be created.

POST	{{url}}/api/apps/{{appID}}/root-environment-group/groups

Request Example

An example POST request for creating an environment group within an application is shown here.

curl --location --request POST '{{url}}/api/apps/{{appID}}/root-environment-group/groups' \
--data-raw '{
    "name": "Dev Group",
    "description": "Dev Group",
    "type": "group",
    "parentId": "Nt6Hj5VIevsVAno7"
}'

Response Example

An example response of the POST request for creating an environment group within an application is shown here.

Status: 201 Created

{
  "name" : "Dev Group",
  "description" : "Dev Group",
  "id" : "0v8kgkkayprnvi7x",
  "parentId" : "Nt6Hj5VIevsVAno7",
  "nativeId" : null,
  "nativeParentId" : null,
  "childGroupIds" : [ ],
  "childEnvironmentIds" : [ ],
  "type" : "group",
  "internalParentId" : ""
}

4. Delete an Environment Group

The DELETE method deletes an environment group within an application for the following applications: AWS Standalone, SalesForce, and ServiceNow.

Request Parameters

The following parameters are possible in the request:

Parameter	Description
appID	The application ID.
envGroupID	The environment group ID.

DELETE

{{url}}/api/apps/{{appID}}/environment-groups/{{envGroupID}}

Request Example

An example DELETE request for deleting an environment group within an application is shown here.

curl --location --request DELETE '{{url}}/api/apps/{{appID}}/environment-groups/{{envGroupID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example

Status: 200 OK

The response only has headers.

Note:

This request does not return a response body.

5. Create an Environment

The POST method creates an environment within an application for the following applications: AWS Standalone, SalesForce, and ServiceNow.

Request Parameters

The following parameters are possible in the request:

Parameter	Description
name	Name of the environment group.
description	An optional description for the group.
type	The environment type is "group".
parentGroupId	The ID of the group under which the environment has to be created.

POST	{{url}}/api/apps/{{appID}}/root-environment-group/environments

Request Example

An example POST request for creating an environment within an application is shown here.

curl --location --request POST '{{url}}/api/apps/{{appID}}/root-environment-group/environments' \
--data-raw '{
    "name": "DevEnv",
    "description": "Dev account",
    "type": "environment",
    "parentGroupId": "0v8kgkkayprnvi7x"
}'

Response Example

An example response of the POST request for creating an environment within an application is shown here.

Status: 201 Created

{
  "id" : "n0erky7u2kfswdyn",
  "name" : "DevEnv",
  "description" : "Dev account",
  "parentGroupId" : "0v8kgkkayprnvi7x",
  "type" : "environment",
  "internalParentId" : "",
  "status" : "active"
}

6. Delete an Environment

The DELETE method deletes an environment within an application for the following applications: AWS Standalone, SalesForce, and ServiceNow.

Request Parameters

The following parameters are possible in the request:

Parameter	Description
appID	The application ID.
envGroupID	The environment group ID.

DELETE

{{url}}/api/apps/{{appID}}/environments/{{envID}}

Request Example

An example DELETE request for deleting an environment is shown here.

curl --location --request POST '{{url}}/api/apps/{{appID}}/environments/{{envID}}' \
--header 'Authorization: TOKEN {{apiToken}}'

Response Example

Status: 200 OK

The response only has headers.

Note:

This request does not return a response body.

7. Details of Accounts

Important Note:

This is the latest API for Details of Accounts.

The GET method fetches the details of all the accounts associated with a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/?page=0&size=20&sort=nativeName,asc&filter=scanStatus eq Unchanged&includeMembers=true

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
includeMembers	This parameter helps to include or exclude the associated permissions and groups in the response. There can be two values: true: When set to true, this parameter includes the associated permissions and groups in the response. false: When set to false, this parameter excludes the associated permissions and groups in the response. The default value is false.	string	Optional
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering accounts. For example, to filter accounts for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving account details is shown here.

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/?page=0&size=20&sort=nativeName&filter=scanStatus%20eq%20Unchanged' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving account details is shown here.

Status: 200 OK

{
    "count": 131,
    "page": 0,
    "size": 20,
    "sort": "nativeName: ASC",
    "filter": "scanStatus eq Unchanged",
    "data": [
        {
            "accountId": 2800,
            "nativeName": "admin1@britive.com",
            "nativeId": "admin1",
            "description": null,
            "lastName": "Admin",
            "firstName": "Admin",
            "created": "2019-09-13T10:15:54Z",
            "modified": null,
            "status": "Unregistered",
            "scanStatus": "Unchanged",
            "privileged": true,
            "type": "Member",
            "permissions": [],
            "scanned": "2019-11-25T15:40:11Z",
            "registrable": false,
            "mappedUsers": []
        }
    ]
}

(Deprecated) Details of Accounts

The GET method fetches the details of all the accounts present in the system.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts

Request Example

An example GET request for retrieving account details is shown here.

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving account details is shown here.

Status: 200 OK

[
    {
        "accountId": 249,
        "nativeId": "Company@yahoo.com",
        "description": null,
        "lastName": null,
        "firstName": null,
        "created": "2020-05-12T20:19:01Z",
        "modified": null,
        "extendedAttributes": {},
        "status": "Unregistered",
        "scanStatus": "New",
        "firstSeen": "2020-09-24T11:38:58Z",
        "lastSeen": null,
        "updated": null,
        "privileged": true,
        "type": "user",
        "userId": null,
        "registrable": true,
        "nativeName": "Company@yahoo.com",
        "scanned": "2020-09-24T11:34:38Z",
        "mappedUsers": [],
        "permissions": [
            {
                "appPermissionId": 6444,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AdministratorAccess",
                "name": "AdministratorAccess",
                "type": "policy",
                "scanStatus": "Added",
                "inherited": null
            },
            {
                "appPermissionId": 6632,
                "tenantAppId": 39,
                "nativeId": "InlinePolicy_to_User(Company@yahoo.com)",
                "name": "InlinePolicy_to_User(Company@yahoo.com)",
                "type": "InlinePolicy",
                "scanStatus": "Added",
                "inherited": null
            }
        ]
    }
]

8. Permissions of an Account

The GET method fetches all the permissions associated with an account for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{acctID}}/permissions?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
acctID	The ID of the account.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering permissions of accounts. For example, to filter permissions of accounts for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving all the permissions associated with an account is shown here.

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{acctID}}/permissions?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving all the permissions associated with an account is shown here.

Status: 200 OK

{
    "count": 3,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "accountId": 2800,
            "permissionId": 46522,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "accountName": "account1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "Administrator",
            "nativeId": {
                "accountNativeId": "a-id1",
                "permissionNativeId": "r-id1"
            },
            "permissionType": "role"
        }
    ]
}

9. Groups of an Account

The GET method fetches the groups associated with an account for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{acctID}}/groups?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
acctID	The ID of the account.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering groups of an account. For example, to filter groups of an account for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving the groups associated with an account is shown here:

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{acctID}}/groups?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving the groups associated with an account is shown here.

Status: 200 OK

{
    "count": 100,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "accountId": 2807,
            "permissionId": 69152,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "accountName": "Account1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "Group1",
            "nativeId": {
                "accountNativeId": "account1",
                "permissionNativeId": "group1"
            },
            "permissionType": "group"
        }
    ]
}

10. Map Accounts

The POST method allows you to map accounts with users.

POST	{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{accountID}}/users

Request Example

An example POST request for mapping an account with a user is shown here.

curl --location --request POST '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{accountID}}/users' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw '{
             "saveToAllEnvs":true
}'

Response Example

Status: 200 OK

The response only has headers.

Note:

This request does not return a response body.

11. Unmap Accounts

The DELETE method allows you to unmap accounts. If you want to enforce checking of the files associated with the account set the forceCheckinPaps parameter as true.

DELETE

{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{accountID}}/users//{{userID}}?forceCheckinPaps=false

Request Example

An example DELETE request for un-mapping accounts is shown here.

curl --location --request DELETE '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/{{accountID}}/users//{{userID}}?forceCheckinPaps=false' \
--header 'Authorization: TOKEN {{token}}' \
--data-raw ''

Response

Status: 200 OK

The accounts are unmapped from the system.

12. Details of Permissions

Important Note:

This is the latest API for Details of Permissions.

The GET method fetches the details of all permissions associated with a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/?page=0&size=20&sort=name,asc&filter=scanStatus eq Unchanged&includeMembers=true

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
includeMembers	This parameter helps to include or exclude the associated accounts and groups in the response. There can be two values: true: When set to true, this parameter includes the associated accounts and groups in the response. false: When set to false (optional value), this parameter excludes the associated accounts and groups in the response. The default value is false.	string	Optional
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering permissions. For example, to filter accounts for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving permissions is shown here:

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/?page=0&size=20&sort=name&filter=scanStatus%20eq%20Unchanged' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving permissions is shown here.

Status: 200 OK

{
    "count": 260,
    "page": 0,
    "size": 20,
    "sort": "name: ASC",
    "filter": "scanStatus eq Unchanged",
    "data": [
        {
            "appPermissionId": 46600,
            "name": "Role1",
            "type": "role",
            "description": "role1",
            "created": "2019-03-11T22:10:54Z",
            "modified": "2019-03-11T23:08:43Z",
            "nativeId": "role1",
            "status": "Registered",
            "scanStatus": "Unchanged",
            "builtIn": true,
            "hasDefinitionsChanged": false,
            "privileged": true,
            "scopeRegistrationId": "scope1",
            "accounts": [],
            "groups": [],
            "permissions": [],
            "scanned": "2019-11-25T15:40:11Z"
        }
    ]
}

(Deprecated) Details of Permissions

The GET method fetches the details of all permissions available in the system.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions?type=permission

Request Example

An example GET request for retrieving permissions is shown here:

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions?type=permission' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving permissions is shown here.

Status: 200 OK

[
    {
        "appPermissionId": 5997,
        "name": "AmazonAppStreamReadOnlyAccess",
        "type": "policy",
        "description": null,
        "created": "2015-02-06T18:40:10Z",
        "modified": null,
        "nativeId": "arn:aws:iam::aws:policy/AmazonAppStreamReadOnlyAccess",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": true,
        "hasDefinitionsChanged": false,
        "privileged": false,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [],
        "permissions": [],
        "groups": []
    },
    {
        "appPermissionId": 5998,
        "name": "AmazonMobileAnalyticsNon-financialReportAccess",
        "type": "policy",
        "description": null,
        "created": "2015-02-06T18:40:36Z",
        "modified": null,
        "nativeId": "arn:aws:iam::aws:policy/AmazonMobileAnalyticsNon-financialReportAccess",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": true,
        "hasDefinitionsChanged": false,
        "privileged": false,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [],
        "permissions": [],
        "groups": []
    },
    ...............................
	...................
	{
        "appPermissionId": 6107,
        "name": "AmazonAppFlowFullAccess",
        "type": "policy",
        "description": null,
        "created": "2020-06-02T23:30:14Z",
        "modified": null,
        "nativeId": "arn:aws:iam::aws:policy/AmazonAppFlowFullAccess",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": true,
        "hasDefinitionsChanged": false,
        "privileged": true,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [],
        "permissions": [],
        "groups": []
    },
    {
        "appPermissionId": 6108,
        "name": "AmazonZocaloFullAccess",
        "type": "policy",
        "description": null,
        "created": "2015-02-06T18:41:13Z",
        "modified": null,
        "nativeId": "arn:aws:iam::aws:policy/AmazonZocaloFullAccess",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": true,
        "hasDefinitionsChanged": false,
        "privileged": true,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [],
        "permissions": [],
        "groups": []
    },
]

13. Accounts Associated with a Permission

The GET method fetches the accounts associated with a permission for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/{{permID}}/accounts?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
permID	The ID of the permission.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering accounts associated with a permission. For example, to filter accounts associated with a permission for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving the accounts associated with a permission is shown here:

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/{{permID}}/accounts?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving accounts associated with a permission is shown here.

Status: 200 OK

{
    "count": 100,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "accountId": 2807,
            "permissionId": 69152,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "accountName": "Account1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "ROle1",
            "nativeId": {
                "accountNativeId": "account1",
                "permissionNativeId": "role1"
            },
            "permissionType": "Role"
        }
    ]
}

14. Groups Associated with a Permission

The GET method fetches the groups associated with a permission for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/{{permID}}/groups?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
permID	The ID of the permission.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering groups associated with a permission. For example, to filter groups associated with a permission for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving the groups associated with a permission is shown here:

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/{{permID}}/groups?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving the groups associated with a permission is shown here.

Status: 200 OK

{
    "count": 100,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "groupId": 2807,
            "permissionId": 69152,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "groupName": "Group1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "Role",
            "nativeId": {
                "groupNativeId": "group1",
                "permissionNativeId": "role1"
            },
            "permissionType": "group"
        }
    ]
}

15. Details of Groups

Important Note:

This is the latest API for Details of Groups.

The GET method fetches the details of all groups associated with a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/?page=0&size=20&sort=name,asc&filter=scanStatus eq Unchanged&includeMembers=true

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
includeMembers	This parameter helps to include or exclude the associated permissions and accounts in the response. There can be two values: true: When set to true, this parameter includes the associated permissions and accounts in the response. false: When set to false, this parameter excludes the associated permissions and accounts in the response. The default value is false.	string	Optional
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering groups. For example, to filter groups for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving group details is shown here.

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/?page=0&size=20&sort=name' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving group details is shown here.

Status: 200 OK

{
    "count": 37,
    "page": 0,
    "size": 20,
    "sort": "name: ASC",
    "filter": null,
    "data": [
        {
            "appPermissionId": 69152,
            "name": "Admins",
            "type": "group",
            "description": null,
            "created": null,
            "modified": null,
            "nativeId": "admins1",
            "status": "Registered",
            "scanStatus": "Unchanged",
            "builtIn": false,
            "hasDefinitionsChanged": false,
            "privileged": true,
            "scopeRegistrationId": "",
            "accounts": [],
            "groups": [],
            "permissions": [],
            "scanned": "2020-02-24T12:28:36Z"
        }
    ]
}

(Deprecated) Details of Groups

The GET method retrieves the details of all the groups within the system.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions?type=group

Request Example

An example GET request for retrieving the group details is shown here.

curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions?type=group' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving the group details is shown here.

Status: 200 OK

[
    {
        "appPermissionId": 6392,
        "name": "Team1",
        "type": "group",
        "description": null,
        "created": "2020-06-28T06:36:59Z",
        "modified": null,
        "nativeId": "Team1",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": false,
        "hasDefinitionsChanged": false,
        "privileged": true,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [
            {
                "accountId": 250,
                "tenantAppId": 39,
                "nativeId": "Team1",
                "nativeName": "Team1",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            },
            {
                "accountId": 251,
                "tenantAppId": 39,
                "nativeId": "PraveenC",
                "nativeName": "PraveenC",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            },
            {
                "accountId": 257,
                "tenantAppId": 39,
                "nativeId": "jenn.smith@gmail.com",
                "nativeName": "jenn.smith@gmail.com",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            },
            {
                "accountId": 258,
                "tenantAppId": 39,
                "nativeId": "testuser1",
                "nativeName": "testuser1",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            }
        ],
        "permissions": [
            {
                "permissionId": 6188,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonS3FullAccess",
                "nativeName": "AmazonS3FullAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6412,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess",
                "nativeName": "AmazonS3ReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6637,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/service-role/AmazonDMSRedshiftS3Role",
                "nativeName": "AmazonDMSRedshiftS3Role",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            }
        ],
        "groups": []
    },
    {
        "appPermissionId": 6688,
        "name": "DevOps",
        "type": "group",
        "description": null,
        "created": "2019-04-03T23:25:59Z",
        "modified": null,
        "nativeId": "DevOps",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": false,
        "hasDefinitionsChanged": false,
        "privileged": false,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [
            {
                "accountId": 257,
                "tenantAppId": 39,
                "nativeId": "jenn.smith@gmail.com",
                "nativeName": "jenn.smith@gmail.com",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            }
        ],
        "permissions": [
            {
                "permissionId": 6059,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AWSOrganizationsReadOnlyAccess",
                "nativeName": "AWSOrganizationsReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6341,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly",
                "nativeName": "AmazonEC2ContainerRegistryReadOnly",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6343,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess",
                "nativeName": "AmazonEC2ReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6412,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess",
                "nativeName": "AmazonS3ReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            }
        ],
        "groups": []
    },
    {
        "appPermissionId": 6689,
        "name": "Developers",
        "type": "group",
        "description": null,
        "created": "2019-04-03T23:26:08Z",
        "modified": null,
        "nativeId": "Developers",
        "status": "Unregistered",
        "tenantAppId": 39,
        "scanStatus": "New",
        "builtIn": false,
        "hasDefinitionsChanged": false,
        "privileged": false,
        "scopeRegistrationId": "",
        "extendedAttributes": {},
        "firstSeen": "2020-09-24T11:38:59Z",
        "lastSeen": null,
        "updated": null,
        "scanned": "2020-09-24T11:34:38Z",
        "accounts": [
            {
                "accountId": 252,
                "tenantAppId": 39,
                "nativeId": "robsmith",
                "nativeName": "robsmith",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            },
            {
                "accountId": 256,
                "tenantAppId": 39,
                "nativeId": "ematil",
                "nativeName": "ematil",
                "scanStatus": "Added",
                "inherited": null,
                "type": "user"
            }
        ],
        "permissions": [
            {
                "permissionId": 6097,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/IAMUserChangePassword",
                "nativeName": "IAMUserChangePassword",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6341,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly",
                "nativeName": "AmazonEC2ContainerRegistryReadOnly",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6343,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess",
                "nativeName": "AmazonEC2ReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            },
            {
                "permissionId": 6412,
                "tenantAppId": 39,
                "nativeId": "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess",
                "nativeName": "AmazonS3ReadOnlyAccess",
                "scanStatus": "Added",
                "inherited": null,
                "type": "policy"
            }
        ],
        "groups": []
    }
]

16. Accounts Associated with a Group

The GET method fetches the accounts associated with a group for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/{{groupID}}/accounts?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
acctID	The ID of the account.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering accounts associated with a group. For example, to filter accounts associated with a group for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving the accounts associated with a group is shown here:

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/{{groupID}}/accounts?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving the accounts associated with a group is shown here.

Status: 200 OK

{
    "count": 100,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "accountId": 2807,
            "permissionId": 69152,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "accountName": "Account1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "Group1",
            "nativeId": {
                "accountNativeId": "account1",
                "permissionNativeId": "group1"
            },
            "permissionType": "group"
        }
    ]
}

17. Permissions Associated with a Group

The GET method fetches the permissions associated with a group for a given application and environment.

The data is returned in multiple pages. To calculate the total number of pages, use the count parameter returned after each API call.

GET	{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/{{groupID}}/permissions?page=0&size=20

Request Parameters

The request parameters used in this method are shown in the following table:

Parameter	Description	Data Type	Required
appID	The ID of the application.	string	Mandatory
envID	The ID of the environment.	string	Mandatory
groupID	The ID of the group.	string	Mandatory
page	The page number starting from zero.	string	Mandatory
size	The number of records that are returned. Note: The total number of records can be used to calculate the number of pages.	string	Optional
sort	The column used for sorting the records.	string	Optional
filter	The filter that you can apply for filtering permissions associated with a group. For example, to filter permissions associated with a group for which scan status has not changed, you can use the following filter: filter: "scanStatus eq Unchanged"	string	Optional

Request Example

An example GET request for retrieving the permissions associated with a group is shown here:

curl --location -g --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/{{groupID}}/permissions?page=0&size=20' \
--header 'Authorization: TOKEN {{token}}'

Response Example

An example response of the GET request for retrieving the permissions associated with a group is shown here.

Status: 200 OK

{
    "count": 100,
    "page": 0,
    "size": 20,
    "sort": null,
    "filter": null,
    "data": [
        {
            "groupId": 2807,
            "permissionId": 69152,
            "scanStatus": "Unchanged",
            "inheritedScope": "scope1",
            "groupName": "Group1",
            "accountPermissionScopes": [
                {}
            ],
            "permissionName": "Role",
            "nativeId": {
                "groupNativeId": "group1",
                "permissionNativeId": "role1"
            },
            "permissionType": "group"
        }
    ]
}

Was this article helpful?

What's Next

Manage Scans