permissions-info

Availability

Breeze 4 and Breeze 5; Connect Enterprise Web Services 6

Description

Returns the list of principals (users or groups) who have permissions to act on a SCO, principal, or account.

To call permissions-info, you must specify an acl-id, which is the ID of a SCO, principal, or account that can be acted on. ACL stands for access control list, and means the list of entities who have permission.

With just an acl-id, permissions-info returns a list of all principals in the account, showing each principal's permission on the principal or SCO specified in the acl-id:

https://example.com/api/xml?action=permissions-info&acl-id=2006258745

To check the permissions a specific principal has on a principal or SCO within an account, call permissions-info with an acl-id and a filter on principal-id:

http://example.com/api/xml?action=permissions-info&acl-id=7
&filter-principal-id=10022

To check the permissions a principal has on an account, call permissions-info with both an acl-id (specifying an account-id) and a principal-id:

https://example.com/api/xml?action=permissions-info
    &acl-id=624520&principal-id=624523

Request URL

http://server_name/api/xml
    ?action=permissions-info
    &acl-id=integer
    &principal-id=integer
    &filter-definition=value
    &sort-definition=value
    &session=BreezeSessionCookieValue

Parameters

Name	Type	Required	Description
`acl-id`	Integer	Y	The ID of a SCO, account, or principal that a principal has permission to act on. The `acl-id` is a `sco-id`, `principal-id`, or `account-id` in other calls.
`principal-id`	Integer	N	The ID of a principal who has a permission (even if `denied`) to act on an object.
`filter-definition`	Filter definition	N	A filter to reduce the volume of the response.
`sort-definition`	Sort definition	N	A sort to return results in a certain sequence.
`session`	String	N	The value of the `BREEZESESSION` cookie. Use this parameter if you do not use a client-side cookie management library.

Filters

You can filter or sort the response on any element or attribute it contains.

Response structure

<?xml version="1.0" encoding="utf-8" ?> 
<results> 
    <status code=allowedValue /> 
    <permissions> 
        <principal principal-id=integer is-primary=boolean type=allowedValue 
                    has-children=boolean permission-id=integer> 
            <name>string</name> 
            <login>string</login> 
        </principal>
    </permissions>
    ...
    <permission acl-id=integer permission-id=allowedValue 
                principal-id=integer /> 
</results>

Response values

Element	Attribute	Type	Description
`results`		Container	All results the action returns.
`status`		Empty, with attributes	The status of the response.
	`code`	Allowed value	A code indicating the response status (see status).
`permissions`		Container	A list of principals showing their permission to access the SCO, account, or principal.
`principal`		Container	Information about one principal showing the principal's permission level on the SCO, account, or principal.
	`principal-id`	Integer	The ID of a principal who has permission on a SCO, account, or principal.
	`is-primary`	Boolean	A value indicating whether the principal is a primary group (same as a built-in group).
	`type`	Allowed value	The type of principal (see type for allowed values).
	`has-children`	Boolean	A value indicating whether the principal has children. Groups have children and users don't, so if `true`, the principal is a group.
	`permission-id`	Allowed value	The permission the principal has on the SCO, account, or principal (see permission-id for values).
	`acl-id`	Integer	The ID of the SCO on which the permission is defined.
`name`		String	The name of the principal who has permission to access the SCO.
`login`		String	The login name of the principal who has permission to access the SCO.
`permission`		Empty, with attributes	Information about the permission one principal has on a SCO, account, or principal. If empty, no permission is defined.
	`acl-id`	Integer	The ID of the object on which the principal has permission.
	`permission-id`	Allowed value	The permission the principal has to act on the object (see permission-id for values).
	`principal-id`	Integer	The ID of the principal who has permission to act on the object.

Sample request

https://example.com/api/xml?action=permissions-info&acl-id=2006334033

Sample response

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="ok" /> 
    <permissions>
        <principal principal-id="2006258745" is-primary="false" type="user" 
                    has-children="false" permission-id="host">
            <name>Joy Smith</name> 
            <login>joy@acme.com</login> 
        </principal>
        ...
    </permissions>
</results>