Rights Locker API Reference

This is the formal description of the API routes for Rights Locker.

API Server: rl.ooyala.com

Note: All requests to the Rights Locker API must be made to the server http://rl.ooyala.com or https://rl.ooyala.com, not https://api.ooyala.com.

MIME Type

When POSTing to create an entitlement, set your MIME type as follows:
Content-type: application/json

Create entitlement

Create an entitlement with identifiers for labels and publishing rules in the POST body.

[POST]/v2/entitlements/providers/pcode/accounts/account_id/content{      
   <Example of POST body>
}

A successful call returns no response body. Look for HTTP response code 200.

Retrieve entitlements

There are two general ways to retrieve entitlements:
  1. Retrieve all entitlements for an account.
  2. Retrieve specific entitlements by asset ID or label ID.

Method #1. Retrieve all entitlements for an account.

[GET]/v2/entitlements/providers/pcode/accounts/account_id/content

Method #2. Retrieve entitlement for a specific asset.

[GET]/v1/entitlements/providers/pcode/accounts/account_id/content/assets/asset_id/external_products/external_product_id

Method #2: Retrieve entitlement for a specific label.

[GET]/v1/entitlements/providers/pcode/accounts/account_id/content/labels/label_id/external_products/external_product_id

Retrieve users for an entitlement

You can retrieve users by asset_id, label_id or offer_id. If you provide a content_type with a corresponding content_id and external_product_id, the response will contain all users who meet the conditions. The maximum number of users in a response is 1000.

If the number of qualified users exceeds 1000, pagination occurs. In this case them response will contain not only users, but also last_shard and last_id. You can append these two parameters to the GET request url to retrieve the next 1000 users.

Retrieve a list of users for an entitlement:

[GET]/v2/entitlements/providers/pcode/users/content_type/content_id/external_products/external_product_id

A successful call returns the list of users:

{
  "users": ["user1","user2", ...]
}

Retrieve a list of users for an entitlement along with last_shard and last_id:

[GET]/v2/entitlements/providers/pcode/users/content_type/content_id/external_products/external_product_id?last_shard=<last_shard>&last_id=<last_id>

A successful calls returns the list of users, the last shard visited and the user ID from the previous response:

{
  "users": ["user1","user2", ...],
  "last_shard": <shard_id>,
  "last_id": <user_id>
}

Delete entitlement

You can delete all of an account's entitlements or entitlements for specific assets or labels.

Remove all of user account_id’s entitlements.

[DELETE]/v2/entitlements/providers/pcode/accounts/account_id/content

A successful call returns no response body.

Remove user account_id’s entitlement to content identified by assets.

Note: Because of the hierarchical nature of labels and their inheritance, deleting an entitlement lower in the label hierarchy has no effect if entitlements higher in the hierarchy still exist. Therefore, when you delete a specific entitlement for a user, check whether the user has entitlements higher in the hierarchy. If so, delete those entitlements, too.
[DELETE]/v2/entitlements/providers/pcode/accounts/account_id/content/assets/asset_id/external_products/external_product_id

A successful call returns no response body.

Remove user account_id’s entitlement to content identified by label_id.

Note: Because of the hierarchical nature of labels and their inheritance, deleting an entitlement lower in the label hierarchy has no effect if entitlement higher in the hierarchy still exists. Therefore, when you delete a specific entitlement for a user, check whether the user has an entitlement higher in the hierarchy. If so, delete that entitlement, too.
[DELETE]/v2/entitlements/providers/pcode/accounts/account_id/content/labels/label_id/external_products/external_product_id

Update an entitlement

To update an entitlement, use the same POST method you used to create it. If the unique combination of label_id, user_id, external_product_id matches an existing entitlement, it is updated.

Example POST body by asset or label

You can define entitlements either by asset or by label; the POST body can include either or both, and the properties are identical for both types.

Note: If you include label or asset identifiers on the route itself, there is no need to include the identifiers in the POST body.
{  
    "assets":[  
        {  
            "content_id":"an_embed_code",
            "publishing_rule_id":"publishing_rule_id",
            "external_product_id":"your_product_id",
            "start_time":YYYY-MM-DDThh:mm:ss,
            "end_time":YYYY-MM-DDThh:mm:ss
        },
        {  
            "content_id":"another_embed_code",
            .  
            .  
            .
        },
        .  
        .  
        .
    ],
    "labels":[  
        {  
            "content_id":"a_label_id",
            "publishing_rule_id":"publishing_rule",
            "external_product_id":"your_product_id",
            "start_time":YYYY-MM-DDThh:mm:ss,
            "end_time":YYYY-MM-DDThh:mm:ss
        },
        {  
            "content_id":"another_label_id",
            .  
            .  
            .
        },
        .  
        .  
        .
    ]   
}

Example POST body by offer

You can define an entitlement by an offer.

{
    "offers":[  
        {  
            "content_id":"an_offer_id",
            "publishing_rule_id":"publishing_rule_id",
            "external_product_id":"your_product_id",
            "start_time":YYYY-MM-DDThh:mm:ss,
            "end_time":YYYY-MM-DDThh:mm:ss
        },               
        {  
            "content_id":"another_offer_id",
            .  
            .  
            .
        },
        .  
        .  
        .
    ]   
}
            

Responses

Rights Locker returns the same HTTP response codes that are returned by Backlot, with the following exceptions:
  • On successful creation via POST, the 200 HTTP response is returned, but no data is returned in the response body.
  • If you search (via GET) for entitlements without any matching results, Rights Locker returns 404, "Not found."

Properties

The following table describes all properties that can be associated with an entitlement.

Property

Description

Required?

assets

An array of asset objects with each object in the array delimited by a comma.
Note: You cannot use external identifiers with Rights Locker. The values passed must be real embed codes (asset IDs).

Type: String

No

content_id

Identifier of either an asset (assets or embed_code) or a label.

For offers, the content_id can be defined as either the offer_id or offer_id:content_group_id. If you use offer_id, a user with this entitlement can watch any content linked to that offer. If you use offer_id:content_group_id, the user can watch only the content under the content_group_id specified here.

Yes

end_time

Ending time of entitlement in UTC (Coordinated Universal Time). Optionally, to specify timezones relative to UTC, you indicate the number of hours to move forward by appending a + (plus sign) and the number of hours. Likewise, you can indicate the number of hours to move backward by appending a - (minus) sign and the number of hours.

Type: dateTime

Example 1: 2013-08-31T23:59:59

Example 2: 2013-08-31T23:59:59+08:00 to indicate a timezone 8 hours forward from UTC.

Default: If omitted, entitlement is infinite.

No

external_product_id

Your own identifier for your product to which this entitlement applies.

Type: String

Valid Values: must not contain reserved URL-related characters (such as [ / & | ]).

Maximum length: 254 characters

Yes

labels

An array of label objects with each object in the array separated by a comma.

No

offers

An array of offer objects with each object in the array separated by a comma. An offer is a global entity that holds monetization options and plans for a given content. A product is a video or group of videos that are monetized and offered to consumers. Products are set up via your eCommerce/payment system’s UI or API.

This feature would be used if your service packages content and offers it as a bundle within a subscription package.

No

publishing_rule_id

Additional restrictions on the user’s entitlement when content is accessed.

No

start_time

Starting time of entitlement in UTC (Coordinated Universal Time). Optionally, to specify timezones relative to UTC, you indicate the number of hours to move forward by appending a + (plus sign) and the number of hours. Likewise, you can indicate the number of hours to move backward by appending a - (minus) sign and the number of hours.

Type: dateTime

Example 1: 2013-08-01T00:00:00

Example 2: 2013-08-01T00:00:00+08:00 to indicate a timezone 8 hours forward from UTC.

Default: If omitted, entitlement is immediate.

No

num_devices_to_bind Upper limit on per-viewer allowable number of devices No
rental_window Defines the rental window {"hours_to_finish":Y}, where Y is the number of hours the user has to finish watching.

Example: "rental_window": {"hours_to_finish":5}

No

Route Attributes

The following attributes are required in the API calls.
Property Definition
account_id

A unique identifier for one of your customers.

Type: String

Valid Values: must not contain reserved URL-related characters (such as [ / & | ]).

Maximum length: 254 characters

pcode A unique identifier of a content provider. Viewable on theBacklot UI ACCOUNT tab, Developers subtab, Partner Code: field.

external_product_id

Your own unique identifier for one of your products.

Type: String

Valid Values: must not contain reserved URL-related characters (such as [ / & | ]).

Maximum length: 254 characters

asset_id

The unique identifier of an asset.

Type: String

label_id

The unique identifier of a label.

Type: String

user_id The unique identifier for a user.

Type: String

api_version The unique identifier for the version number.

Type: Int

content_id The unique identifier for the content (asset, label or offer).

Type: String

content_type The unique identifier to indicate the type (asset, label or offer) to use as a key in the query.

Type: String

external_product_id The unique identifier to indicate the entitlement.

Type: String

last_id (optional) The last user id in the previous response.

Type: String

last_shard (optional) The unique identifier of the last shard visited.

Type: Int

Was this article helpful?