Authorization

Ubstream REST API allows to manage the authorizations of two kind of resources:

• collections
• medias

Scopes

In the following section a singular authorization will be named a scope.

Each kind of resource has its own list of scopes.

Collections scopes

• scope:library-collection:access: Grant access on the collection
• scope:library-collection:edit: Grant edition capability
• scope:library-collection:edit-permissions: Grant authorization management capability
• scope:library-collection:delete: Grant delete capability
• scope:library-collection:download: Grant download capability (need access too)
• scope:library-collection:access-media-stats: Grant access on media's statistics
• scope:library-collection:create-resource: Grant sub resources (collection or media) creation.

Medias scopes

• scope:media:access: Grant access on the media
• scope:media:edit: Grant edition capability
• scope:media:edit-permissions: Grant authorization management capability
• scope:media:delete: Grant delete capability
• scope:media:download: Grant download capability (need access too)
• scope:media:access-stats: Grant access on media's statistics

Authorizations grid

When manipulating authorizations, it is important to understand the data structure of the resource's authorization grid.

A grid contains three categories:

• everybody: One single grid line to manage authorizations for all users. Only access and download scopes can be used.
• groups: Multiple grid lines to manage authorizations for groups of users.
• users: Multiple grid lines to manage users authorizations directly.

There are two ways for manipulating authorizations grids:

• Read or modify a full authorization grid: Should be used when modifying several lines on the grid.
• Read, modify or delete a line (everybody, group or user) of an authorization grid. Should be used when modifying only one line of the grid.

Example of collection authorizations grid

{
  "hash": "cee27229bf107d83c9fa17ceb3eef529fa8848fafef1de50da751ce35d3e2355",
  "everybody": {
    "scopes": []
  },
  "groups": [
      {
          "id": "13d7eea3-dd42-438e-bf97-c117c62d3af9",
          "name": "Friends",
          "scopes": [
              "scope:library-collection:access",
              "scope:library-collection:edit"
          ]
      }
  ],
  "users": [
    {
      "id": "e11d100e-0498-430a-84f0-c4d48efca1ab",
      "username": "t.jerry",
      "displayName": "Tom Jerry",
      "scopes": [
        "scope:library-collection:access",
        "scope:library-collection:edit"
      ]
    },
    {
      "id": "9762b952-381b-475b-8b43-c060f96ea20d",
      "username": "j.doe",
      "displayName": "John Doe",
      "scopes": [
        "scope:library-collection:access",
        "scope:library-collection:edit",
        "scope:library-collection:delete",
        "scope:library-collection:edit-permissions",
        "scope:library-collection:access-media-stats",
        "scope:library-collection:download",
        "scope:library-collection:create-resource"
      ]
    }
  ]
}

Propagation

When modifying collections authorizations, a propagation strategy can be used if you want to apply your modifications on children entities recursively.

There are three available strategies:

• do_not_propagate: Do not apply any modifications on children entities. This is the fefault behaviour.
• merge: Apply modified lines on children entities.
• overwrite: Erase children authorizations grids with current grid lines. Can be used ONLY when using endpoints that concern full authorizations grids

Note: When using merge or overwrite propagation strategies, a requestId property will be returned inside the response data. This can be used to know when the propagtion is completed (see Asynchronous requests)

Concurrent modifications

To modify an authorization grid, it's usually necessary to read it before in order to get its content. So it can happen that another user did a modification between the two requests (read and update).

Every GET (read) request on authorizations endpoints returns a property hash in response data. The hash value can be passed back into the PUT (update) request in order to prevent any concurrent modification.

In this case, the response will have a Status Code 409 (Conflict) and contain the following data as JSON format

{
  "$diagnoses": [
    {
      "$severity": "error",
      "$message": "Please enter another value",
      "$code": 11007,
      "$detail": "ErrorCode=DEPRECATED_AUTHZ_UPDATE_REQUEST(11007): Authorization of resource 791e883e-3627-4f5f-9b2d-6f8b3323b741 is deprecated, refresh your grid"
    }
  ]
}