Permission

Note: Only BeBanjo accounts configured for User Permissions will expose permissions in the API.

A Permission represents a group of item level actions a user can perform over the catalogue items, each of those actions are represented by different keys.

This is how a permission looks like:

<?xml version="1.0" encoding="UTF-8"?>
<permission>
  <id type="integer">3</id>
  <name>contribute</name>
  <level type="integer">2</level>
  <keys>item:read item:update item:contribute item:share item:clips contribute:update</keys>
  <link rel="self" href="https://movida.bebanjo.net/api/permissions/3"/>
</permission>

{
  "resource_type": "permission",
  "id": 3,
  "name": "contribute",
  "level": 2,
  "keys": "item:read item:update item:contribute item:share item:clips contribute:update",
  "self_link": "https://movida.bebanjo.net/api/permissions/3"
}

The self link is pointing to the permission itself, and it is a unique URL that will not change overtime.

Valid attributes

• id (required): BeBanjo internal identifier of the permission.

• name (required): the name of the permission.

• keys (required): the keys associated to the permission. It includes all the keys associated to permissions with lower level, plus specific additional keys.

• level (required): the level of the permission. A user with certain role level can be granted with item level permissions with minor or equal level.

Get a list of all permissions in the current account

Permissions are linked from the root of the API, through the link identified with the rel="permissions" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="permissions" href="https://movida.bebanjo.net/api/permissions">
</movida>

{
  // ...
  "permissions_link": "https://movida.bebanjo.net/api/permissions",
  // ...
}

Following that link, we can fetch the list of permissions in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/permissions

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/permissions

<?xml version="1.0" encoding="UTF-8"?>
<permissions type="array">
  <total-entries>53</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/permissions?page=2"/>
  <permission>
    <id type="integer">1</id>
    <name>view</name>
    <level type="integer">0</level>
    <keys>item:read</keys>
    <link rel="self" href="https://movida.bebanjo.net/api/permissions/1"/>
  </permission>
  <permission>
    <id type="integer">2</id>
    <name>edit</name>
    <level type="integer">1</level>
    <keys>item:read item:update contributor:update</keys>
    <link rel="self" href="https://movida.bebanjo.net/api/permissions/2"/>
  </permission>
  <!-- ... -->
</permissions>

{
  "total_entries": 53,
  "next_link": "https://movida.bebanjo.net/api/permissions?page=2",
  "entries": [
    {
      "resource_type": "permission",
      "id": 1,
      "name": "view",
      "level": 0,
      "keys": "item:read",
      "self_link": "https://movida.bebanjo.net/api/permissions/1"
    },
    {
      "resource_type": "permission",
      "id": 2,
      "name": "edit",
      "level": 1,
      "keys": "item:read item:update contributor:update",
      "self_link": "https://movida.bebanjo.net/api/permissions/2"
    },
    // ...
  ]
}

Note: This is a paginated resource. By default, only 50 permissions will be included in each page but you can override this default by using the per_page parameter described in the next section. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

You can filter the list of permissions returned using the following attributes:

• per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get a single permission given its URL

The self link of a permission contains a URL that will allow us to fetch that individual permission:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/permissions/3

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/permissions/3

<?xml version="1.0" encoding="UTF-8"?>
<permission>
  <id type="integer">3</id>
  <name>contribute</name>
  <level type="integer">2</level>
  <keys>item:read item:update item:contribute item:share item:clips contribute:update</keys>
  <link rel="self" href="https://movida.bebanjo.net/api/permissions/3"/>
</permission>

{
  "resource_type": "permission",
  "id": 3,
  "name": "contribute",
  "level": 2,
  "keys": "item:read item:update item:contribute item:share item:clips contribute:update",
  "self_link": "https://movida.bebanjo.net/api/permissions/3"
}