Skip to main contentIBM Video Streaming Developers

Custom Roles

Get a list of Custom Roles

This API call is used to get a list of custom roles inside an Organization.

GET https://api.video.ibm.com/organizations/{organizationId}/custom-roles.json

Query Parameters

PARAMETERTYPEIMPORTANCEDESCRIPTION
pagenumberOPTIONALPage number. The first page’s index is 1
pagesizenumberOPTIONALSize of a page. 1 <= pagesize <= 50

Example of the request:

GET /organizations/ZzzqXZ/custom-roles.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950

Note that the token in the above call is only an example.

Success response

Upon success, a set of key-value pairs is returned under a custom_roles element with an HTTP Status code of 200.

KEYTYPEDESCRIPTION
idstringID
namestringName
permissionstringID of the Permission associated to this Custom Role. You have to use this ID when assigning Custom Roles to administrators on a Channel
children_countnumberNumber of permissions associated to this Custom Role
user_countnumberNumber of administrators associated to this Custom Role

Additionally there is a paging element in the response with the following values:

KEYTYPEDESCRIPTION
previousstringLink to the previous page (if exists)
nextstringLink to the next page (if exists)
page_countnumberNumber of available pages
item_countnumberTotal number of items

Example of a success response:

{
"custom_roles": [
{
"id": "42",
"name": "Video uploaders",
"permission": "7b79a268b5f2a7740c639dadae3eec7f",
"children_count": 3,
"user_count": 10
},

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 ForbiddenThe provided access token has no access to the user
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Create a custom role

This API call is used to create a custom role inside an Organization.

POST https://api.video.ibm.com/organizations/{organizationId}/custom-roles.json

Parameters

KEYTYPEIMPORTANCEDESCRIPTION
namestringREQUIREDName
childrenarrayREQUIREDPermissions associated with the Custom Role

Permissions

NAMEDESCRIPTION
broadcast.startStart broadcast
video.publishPublish videos
video.unpublishUnpublish videos
video.manage_publishedManage published videos
video.downloadDownload videos
video.deleteDeleted videos
channel.access_controlEdit channel level Access Control (Enterprise Video Streaming only)
channel.view_ivtSee and download individual viewer statistics

The Content-Type of the request should be application/x-www-form-urlencoded.

Example of the request:

POST /organizations/ZzzqXZ/custom-roles.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
name=My%20first%20Custom%20Role&children[]=video.download&children[]=channel.view_ivt

Note that the token in the above call is only an example.

Success response

Upon success, a set of key-value pairs is returned with an HTTP Status code of 201.

KEYTYPEDESCRIPTION
idstringID
namestringName
resourcestringResource that the Custom Role is associated with
permissionstringID of the Permission associated to this Custom Role. You have to use this ID when assigning Custom Roles to administrators on a Channel
childrenarrayPermissions associated with the Custom Role

Example of a success response:

{
"id": "999",
"name": "My first Custom Role",
"resource": "organization:5542/",
"permission": "1442ad8919caec4e3fc86a3e8063f8eb",
"children": ["video.download", "channel.view_ivt"]
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
400 Bad RequestWe couldn’t create a new Custom Role (eg.: name is already exists)
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 ForbiddenThe provided access token has no access to the user
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Get a Custom Role

This API call is used to get information about a Custom Role inside an Organization.

GET https://api.video.ibm.com/organizations/{organizationId}/custom-roles/{customRoleId}.json

Query Parameters

PARAMETERTYPEIMPORTANCEDESCRIPTION
pagenumberOPTIONALPage number. The first page’s index is 1
pagesizenumberOPTIONALSize of a page. 1 <= pagesize <= 50

Example of the request:

GET /organizations/ZzzqXZ/custom-roles/999.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950

Note that the token in the above call is only an example.

Success response

Upon success, a set of key-value pairs is returned with an HTTP Status code of 200.

KEYTYPEDESCRIPTION
idstringID
namestringName
resourcestringResource that the Custom Role is associated with
permissionstringID of the Permission associated to this Custom Role. You have to use this ID when assigning Custom Roles to administrators on a Channel
childrenarrayPermissions associated with the Custom Role

Example of a success response:

{
"id": "999",
"name": "My first Custom Role",
"resource": "organization:5542/",
"permission": "1442ad8919caec4e3fc86a3e8063f8eb",
"children": ["video.download", "channel.view_ivt"]
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 ForbiddenThe provided access token has no access to the user
404 Not FoundCustom Role doesn’t exist under the Organization
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Update a Custom Role

This API call is used to update the permissions of a custom role inside an Organization.

PUT https://api.video.ibm.com/organizations/{organizationId}/custom-roles/{customRoleId}.json

Parameters

KEYTYPEIMPORTANCEDESCRIPTION
namestringREQUIREDName
childrenarrayREQUIREDPermissions associated with the Custom Role

The Content-Type of the request should be application/x-www-form-urlencoded.

Example of the request:

PUT /organizations/ZzzqXZ/custom-roles/999.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
name=My%20first%20Custom%20Role&children[]=video.download&children[]=channel.view_ivt

Note that the token in the above call is only an example.

Success response

Upon success, a set of key-value pairs is returned with an HTTP Status code of 201.

KEYTYPEDESCRIPTION
idstringID
namestringName
resourcestringResource that the Custom Role is associated with
permissionstringID of the Permission associated to this Custom Role. You have to use this ID when assigning Custom Roles to administrators on a Channel
childrenarrayPermissions associated with the Custom Role

Example of a success response:

{
"id": "999",
"name": "My first Custom Role",
"resource": "organization:5542/",
"permission": "1442ad8919caec4e3fc86a3e8063f8eb",
"children": ["video.download", "channel.view_ivt"]
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
400 Bad RequestWe couldn’t create a new Custom Role (eg.: name is already exists)
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 ForbiddenThe provided access token has no access to the user
404 Not FoundCustom Role doesn’t exist under the Organization
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Delete a Custom Role

This API call is used to delete a Custom Role from inside an Organization.

DELETE https://api.video.ibm.com/organizations/{organizationId}/custom-roles/{customRoleId}.json

Example of the request:

DELETE /organizations/ZzzqXZ/custom-roles/999.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950

Note that the token in the above call is only an example.

Success response

Upon success the response body is empty with an HTTP Status code of 204.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 ForbiddenThe provided access token has no access to the user
404 Not FoundCustom Role doesn’t exist under the Organization
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request