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

Name

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

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy