Access controls

Managing access controls

In the text below only /item/ resource is specified but the same syntax applies for the /collection/ resource.

Retrieve access control list for an item

GET /item/(item-id)/access/

Retrieves the entire access control list for the specified item.

Produces:
Role:

_accesscontrol_read

Add a new entry access control entry

POST /item/(item-id)/access/

Adds a new access control entry for the specified item.

Accepts:
Produces:
  • text/plain – The id of the created entry.
Role:

_accesscontrol_write

Example

POST /item/VX-123/access/
Content-Type: application/xml

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <permission>READ</permission>
   <group>testGroup</group>
   <operation>
      <uri/>
   </operation>
</AccessControlDocument>

Retrieve a specific access control entry

GET /item/(item-id)/access/(access-id)

Retrieves the desired access control entry.

Status Codes:
  • 404 Not found – No entry with that id exists in that item.
Produces:
  • application/xml, application/json – An AccessControlDocument containing the requested access control entry.
Role:

_accesscontrol_read

Delete a specific access control entry

DELETE /item/(item-id)/access/(access-id)

Removes the desired access control entry.

Status Codes:
  • 200 OK – The entry was successfully removed.
  • 404 Not found – No entry with that id exists in that item.
Role:

_accesscontrol_write

Add access control entries to all items

POST /item/access/

Adds access control entries to all known items.

Accepts:
Role:

_administrator

Remove all access control entries from all items

DELETE /item/access/

Deletes all access control entries from all known items.

Role:_administrator

Default access controls

Each user can specify what access control that will be applied to an imported item. The user importing the item will always be granted OWNER permissions.

List the default access controls for the current user

GET /import/access/

Lists the access control list that will be applied on imported items.

Produces:
Role:

_import

Example

GET /import/access
<ImportAccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <name>mygroup</name>
      <permission>READ</permission>
   </group>
</ImportAccessControlListDocument>

Add a group to the default access control list

PUT /import/access/group/(group-name)

Sets the permissions for a certain group.

Query Parameters:
 
  • permission – The level of permissions to grant the group.
Role:

_import

Example

PUT /import/access/group/mygroup?permission=READ
200 OK

Remove a group from the default access control list

DELETE /import/access/group/(group-name)

Removes the specified group from the default access control list.

Role:_import

Example

DELETE import/access/group/mygroup
200 OK

Viewing applied access controls

To review all access control entries that affects an item an AccessControlMergedDocument can be retrieved.

Retrieve a list of applied access control entries

There are two modes of operation, either retrieving the access on the item for all users or querying for the access of a specific user. In the former case no parameters are specified and in the latter all parameters must be supplied. The entries will be listed according to priority for every user. If the access is given through a group or a collection, the names and ids of those will be given.

GET /item/(item-id)/merged-access/
Query Parameters:
 
  • username – The name of the user to check.
  • permission – The lowest required permission level.
  • type – The type of operation to check for.
Produces:
Role:

_accesscontrol_read

Example: retrieving all entries

GET /item/VX-250
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access priority="1" id="VX-3111" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access priority="2" id="VX-24112" username="admin">
    <permission>WRITE</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="3" id="VX-4119" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-23</collection>
  </access>
  <access priority="4" id="VX-2221" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access priority="5" id="VX-2205" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="1" id="VX-24090" username="test">
    <permission>READ</permission>
    <type>METADATA</type>
    <group>mygroup</group>
  </access>
</AccessControlMergedDocument>

Example: querying about specific access

Checking if the user admin has full access to the metadata of item VX-250. Notice that the access provided by VX-24112 does not match, but it is less prioritized than the access of VX-3111 and thus the user has full access to the metadata.

GET /item/VX-250/merged-access?username=admin&permission=ALL&type=METADATA
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <query>
    <username>admin</username>
    <permission>ALL</permission>
    <type>METADATA</type>
    <item>VX-250</item>
  </query>
  <access priority="1" matches="true" id="VX-3111">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access priority="2" matches="false" id="VX-24112">
    <permission>WRITE</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="3" matches="true" id="VX-4119">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-23</collection>
  </access>
  <access priority="4" matches="true" id="VX-2221">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access priority="5" matches="true" id="VX-2205">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
</AccessControlMergedDocument>

Retrieve a list of applied access control entries that affects groups

GET /item/(item-id)/merged-access/group

Lists groups that have access to an item.

Even though a user belongs to a group that has access to an item, the user may not have access due to other access control entries that take precedence.

Groups without users will not appear, unless the group belongs to an inheritance hierarchy that has users.

Query Parameters:
 
  • full
    • true - Return all access controls that apply for a group. Also include additional information about the access controls in the response.
    • false (default) - Return a single access entry with the permission that applies for each group and type.

    New in version 4.2.3.

Produces:
Role:

_accesscontrol_read

Example

GET /item/VX-1000/merged-access/group
<AccessControlMergedGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access>
    <group>groupA</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>_transcoder</group>
    <permission>WRITE</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>_special_all</group>
    <permission>WRITE</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupD</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupC</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupB</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
</AccessControlMergedGroupDocument>