Name
Last updated on
May 15, 2021
Find information about what permissions a principal has on a SCO, an account, or on a principal. Also, fetches the group and child information of the principal.
Availability
Breeze 4
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
|
|
Type |
Required |
Description |
|
acl-id |
BIGINT |
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 |
BIGINT |
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 training-group-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 | BIGINT |
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 | BIGINT |
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 | BIGINT |
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 | BIGINT |
The ID of the principal who has permission to act on the object. |
|
| training-group-id | BIGINT |
The ID of the training group. |
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" training-group-id="2007842424"> <name>Joy Smith</name> <login>joy@acme.com</login> </principal> ... </permissions> </results>
See also
