ListAuthorizedUsers-阿里云帮助中心

Queries the list of authorized users for a specified delivery group or delivery group set by using paging. Supports exact or fuzzy filtering by username.

Operation description

This operation queries the currently authorized users of a specified delivery group (AppInstanceGroupId) or delivery group set (AppInstanceGroupSetId). It returns each user's username, account type, email address, phone number, and the authorization mode of the associated delivery group.

This operation returns authorization relationships and does not indicate whether users are currently online or have established connections.
In the Cloud Browser product, a delivery group corresponds to a cloud browser group, and a delivery group ID corresponds to a browser group ID.

The scope of results depends on the authorization mode of the delivery group (response parameter AuthMode):

When the authorization mode is App (application-level authorization) or AppInstanceGroup (delivery group-level authorization): Returns users authorized through the AuthorizeInstanceGroup operation at the delivery group level, as well as users authorized through the AuthorizeUsersForApp operation at the application level. If AppId is specified, only users authorized for that specific application are returned.
When the authorization mode is Session (session-level authorization): Returns users who have been granted persistent sessions. The AppInstancePersistentIds field lists all persistent session IDs granted to each user. If AppInstancePersistentId is specified, only users granted that session are returned.
When querying by delivery group set: Returns users authorized for the set. The response parameter AppInstanceGroupId is the primary delivery group ID of the set, and AppInstanceGroupSetId is the queried set ID.

When querying by delivery group, results are sorted in descending order by authorization time, with the most recently authorized users listed first.

Before you begin

The target delivery group or delivery group set must be created, belong to the current account, and match the specified ProductType. Otherwise, a resource-not-found error code is returned.
Users must have been authorized through the AuthorizeInstanceGroup or AuthorizeUsersForApp operation. If no users have been authorized, the operation returns normally with an empty Users list and TotalCount of 0.

Parameter description

ProductType, PageNumber, and PageSize are required. If ProductType has an invalid value, the error code ProductTypeInvalid is returned.
Exactly one of AppInstanceGroupId and AppInstanceGroupSetId must be specified. If both or neither are specified, the error code InvalidParameter.AppInstanceGroupId/AppInstanceGroupSetId is returned.
AppId and AppInstancePersistentId are not supported when querying by delivery group set. If specified, the error codes InvalidParameter.AppId and InvalidParameter.AppInstancePersistentId are returned respectively.
EndUserId performs exact matching by username. UserIdFuzzy performs fuzzy matching by username (a hit occurs if the username contains the keyword). Both can be specified simultaneously, in which case both conditions must be met.
PageNumber starts from 1. Valid values of PageSize: 1 to 100.
When the authorization mode is App or AppInstanceGroup, TotalCount is the number of authorization records that match the conditions. If the same user has multiple authorization records (for example, authorized for multiple applications), the records are merged into a single user entry in Users. Therefore, the number of users returned on the current page may be less than PageSize. Use TotalCount to determine whether to continue paging. When the authorization mode is Session, TotalCount is the deduplicated user count.

Call sequence

Call the ListAppInstanceGroup operation to obtain the delivery group ID. For cloud browser groups, call the ListBrowserInstanceGroup operation.
Call the AuthorizeInstanceGroup operation to authorize at the delivery group level, or call the AuthorizeUsersForApp operation to authorize at the application level.
Call this operation to query authorized users. To remove authorization, pass the returned EndUserId values to the UnAuthorizeUserIds parameter of the authorization operations mentioned above.

Error codes

ProductTypeInvalid: The value of ProductType is invalid.
InvalidParameter.AppInstanceGroupId/AppInstanceGroupSetId: Both AppInstanceGroupId and AppInstanceGroupSetId are specified, or neither is specified.
InvalidParameter.AppId: AppId is specified when querying by delivery group set.
InvalidParameter.AppInstancePersistentId: AppInstancePersistentId is specified when querying by delivery group set.
InvalidAppInstanceGroupSpecItem.NotFound: The delivery group does not exist, does not belong to the current account, or the product type does not match.
InvalidBrowserInstanceGroup.NotFound: When ProductType is CloudBrowser, the cloud browser group does not exist, does not belong to the current account, or the product type does not match.
InvalidAppInstanceGroupSet.NotFound: The delivery group set does not exist, does not belong to the current account, the product type does not match, or the set does not have an available primary delivery group.
InvalidAppInstanceGroupSet.ActivationFailed: The delivery group set is not in an available state.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
ProductType	string	Yes	The product type. The value must match the product type of the queried delivery group or delivery group set. If the value does not match, a resource-not-found error code is returned. Valid values: CloudApp: Wuying Cloud Application. CloudBrowser: Cloud Browser. WuyingServer: Enterprise Edition Workstation. WuyingWorkstation: Personal Edition Linggou Container Workstation. WuyingWorkstationTeam: Linggou Team Edition Container Workstation. WuyingWorkstationBusiness: Linggou Dedicated Edition Container Workstation. AndroidCloud: Cloud Phone. AIAgent: AgentBay (AI agent). Valid values: CloudBrowser : Cloud Browser.	CloudApp
PageSize	integer	Yes	The number of records per page. Valid values: 1 to 100. When the authorization mode is `App` or `AppInstanceGroup`, pagination is based on authorization records. Multiple authorization records for the same user are merged into a single user entry. Therefore, the actual number of users returned on the current page may be less than this value.	20
PageNumber	integer	Yes	The page number, starting from 1.	1
AppInstanceGroupId	string	No	The delivery group ID. Call the ListAppInstanceGroup operation to obtain this value. For cloud browser groups, specify the browser group ID returned by the ListBrowserInstanceGroup operation. Exactly one of this parameter and AppInstanceGroupSetId must be specified.	aig-9ciijz60n4xsv****
AppInstanceGroupSetId	string	No	The delivery group set ID. Exactly one of this parameter and AppInstanceGroupId must be specified. When querying by set, do not specify AppId or AppInstancePersistentId. Otherwise, a parameter error is returned.	set-3jm9d0abc00example
AppId	string	No	The application ID. Specifies the application to filter users who are authorized for that specific application (authorized through the AuthorizeUsersForApp operation). This parameter applies to delivery groups with the `App` authorization mode. Obtain the application ID from the Apps list returned by the GetAppInstanceGroup operation. If not specified, all authorized users under the delivery group are returned. This parameter is not supported when querying by delivery group set.	ca-i87mycyn419nu****
EndUserId	string	No	The username for exact matching. If not specified, no filtering by exact username is applied. Can be specified together with UserIdFuzzy, in which case both conditions must be met.	alice
UserIdFuzzy	string	No	The username keyword for fuzzy matching. A match occurs if the username contains this keyword. For example, if you specify `ali`, both `alice` and `ali.wang` are returned. If not specified, no keyword-based filtering is applied.	ali
AppInstancePersistentId	string	No	The persistent session ID. Specifies the persistent session to filter users who are granted that session. This parameter applies to delivery groups with the `Session` authorization mode. Call the ListPersistentAppInstances operation to obtain this value. If specified, only users granted that session are returned. However, the response parameter AppInstancePersistentIds still lists all persistent sessions granted to each user. This parameter is not supported when querying by delivery group set.	p-0cc7s3mw2fg4j****

Response elements

Element	Type	Description	Example
	object	The paging result of the authorization user query.
PageNumber	integer	The current page number, which is the same as the PageNumber request parameter.	1
PageSize	integer	The number of records per page, which is the same as the PageSize request parameter.	20
RequestId	string	The request ID.	5C1A4F2D-713A-5C98-8AF6-1B5D0868****
TotalCount	integer	The total number of records that match the query conditions. Use this value to determine whether to continue paging. When the authorization mode is `App` or `AppInstanceGroup`, this is the number of authorization records. If the same user has multiple authorization records, the user is counted multiple times. Therefore, this value may be greater than the actual number of users. When the authorization mode is `Session`, this is the deduplicated user count.	1
Users	array<object>	The list of authorized users on the current page. Multiple authorization records for the same user are merged into a single entry. An empty list is returned if no authorized users match the conditions.
	object	The information about an authorized user.
AccountType	string	The account type of the user. Valid values: simple: Convenience account. ad: Active Directory (AD) domain account, which originates from an enterprise AD domain. Valid values: ad : AD domain account. simple : convenience account.	simple
AppId	string	The application ID. Returned only when AppId is specified in the request. The value is the same as the request parameter. Not returned if AppId is not specified or when querying by delivery group set.	ca-i87mycyn419nu****
AppInstanceGroupId	string	The delivery group ID associated with the user's authorization relationship. When querying by delivery group, this value is the same as the request parameter. When querying by delivery group set, this value is the primary delivery group ID of the set.	aig-9ciijz60n4xsv****
AppInstanceGroupSetId	string	The delivery group set ID. Returned only when querying by delivery group set. The value is the same as the AppInstanceGroupSetId request parameter.	set-3jm9d0abc00example
AppInstancePersistentIds	array	The list of persistent session IDs granted to the user. Returned only when the delivery group authorization mode (AuthMode) is `Session`. This list is not affected by the AppInstancePersistentId request parameter and always includes all persistent sessions granted to the user.
	string	The persistent session ID.	p-0cc7s3mw2fg4j****
AuthMode	string	The authorization mode of the delivery group, which determines the scope of results returned by this operation. Valid values: App: Application-level authorization. Applications within the delivery group are authorized to users without restricting which sessions the users can use. Session: Session-level authorization. Persistent sessions within the delivery group are authorized to users without restricting which applications the users can use. In this case, AppInstancePersistentIds returns the persistent sessions granted to the user. AppInstanceGroup: Delivery group-level authorization. The entire delivery group is authorized to users, allowing them to open any application using any session within the delivery group. When querying by delivery group set, the authorization mode of the primary delivery group in the set is returned. Valid values: App : application-level authorization. AppInstanceGroup : delivery group-level authorization. Session : session-level authorization.	AppInstanceGroup
Email	string	The email address of the user. Returned only when the account information of the user can be retrieved.	alice@example.com
EndUserId	string	The username. To remove authorization, pass this value to the UnAuthorizeUserIds parameter of the AuthorizeInstanceGroup or AuthorizeUsersForApp operation.	alice
IsAuthAllApps	string	Indicates whether the query is not restricted to a specific application. Valid values: true: AppId is not specified in the request. All authorized users under the delivery group are returned. false: AppId is specified in the request. Only users authorized for that specific application are returned. Note This field is determined by whether the AppId request parameter is specified. It does not reflect the actual scope of applications authorized to the user and cannot be used to determine whether the user is authorized for all applications. Valid values: true : not restricted to a specific application. false : restricted to a specific application.	true
Phone	string	The phone number of the user. Returned only when the account information of the user can be retrieved.	138****0000

Examples

Success response

JSON format

{
  "PageNumber": 1,
  "PageSize": 20,
  "RequestId": "5C1A4F2D-713A-5C98-8AF6-1B5D0868****",
  "TotalCount": 1,
  "Users": [
    {
      "AccountType": "simple",
      "AppId": "app-3jm9d0abc00example",
      "AppInstanceGroupId": "big-3jm9d0abc00example",
      "AppInstanceGroupSetId": "set-3jm9d0abc00example",
      "AppInstancePersistentIds": [
        "ai-3jm9d0abc00example"
      ],
      "AuthMode": "AppInstanceGroup",
      "Email": "alice@example.com",
      "EndUserId": "alice",
      "IsAuthAllApps": "true",
      "Phone": "138****0000"
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.