Use the license controller to create and manage license templates and to assign those templates to mediacontainers.
License templates
License templates allow you to define reusable license structures that can be assigned to multiple mediacontainers.
A template contains all relevant license information — usage types, contacts, metadata, personal rights, and usage restrictions — and serves as the basis for individual licenses. Before a template can be assigned to a mediacontainer, it must be **locked** (flag `10`).
Locking a template ensures that all derived licenses remain consistent and cannot be affected by subsequent changes to the template. Use the `lockLicense` parameter when creating or updating a template to lock it. To unlock a template, set `lockLicense` to `false` and provide an `unlockReason`.
Each template requires at least:
- A `license_name` and `license_description` in the `metadata` array
- At least one contact of type `licensor` in the `contacts` array
Licenses
Once a license template is locked, it can be assigned to a mediacontainer by creating a license with the corresponding `templateId` and `mediaContainerId`. The template data is merged with any additional parameters you send.
A mediacontainer can have multiple licenses, including multiple licenses based on the same template (e.g. for different usage types, regions, or licensing periods).
When a license is assigned to a mediacontainer, the following happens automatically:
- If no `settings.startDate` is set on the mediacontainer, it will be set to the license’s `start` date. `startDateSetBy` will be set to `{ type: “license”, id: <licenseId> }`.
- If no `settings.endDate` is set on the mediacontainer, it will be set to the license’s `end` date. `endDateSetBy` will be set to `{ type: “license”, id: <licenseId> }`.
These values can be overwritten manually, but the license watcher (see below) will continue to monitor and enforce the license end date regardless.
License Watcher
If a license has an `end` date set, the license watcher service automatically monitors all affected mediacontainers and deactivates them when the license expires — helping you avoid claims for wrongful usage of assets.
The license watcher will deactivate a mediacontainer (set flag `9`) when the license expires, **unless**:
- the license has `settings.behaviour.ignoreAutoDeactivate` set to `true` — use this if you want to manage deactivation yourself and opt out of automatic enforcement.
- the license has `settings.behaviour.ignoreForMediaContainerSettings` set to `true` — use this if the license should not influence the mediacontainer’s `startDate`/`endDate` settings at all. This is useful when a license is assigned purely for documentation purposes without affecting the mediacontainer’s availability
- The mediacontainer is already deactivated – see MediaContainer Controller
When a mediacontainer is deactivated by the license watcher, the event `unpublished_because_licenseEnd` is added to its event history.
Note: If you manually re-activate a mediacontainer after the license watcher has deactivated it, it will not be automatically deactivated again.
Please also read about start and end date in section Availability of mediacontainers for external publishing at MediaContainer Controller
Reference
License find
GET/v5/license
Find license templates for the customer or licenses for a given mediaContainerId.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| mediaContainerId | integer | ✗ | Return licenses for the given mediaContainer id |
| refresh | boolean | ✗ | If true, data in cache is invalidated and result comes fresh from database |
Response
| Field | Type | Description |
|---|---|---|
| contacts | array | Array of contact objects assigned to this license. |
| └ id | integer | Unique identifier of this license-contact relation. |
| └ licenseId | integer | Id of the license this contact belongs to. |
| └ contactId | integer | Id of the contact. |
| └ type | string | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | Optional notes for this contact relation. |
| └ flag | boolean | Flag of this contact relation. |
| └ creatorId | integer | Id of the user who created this contact relation. |
| └ customerId | integer | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | Timestamp when this contact relation was last updated. |
| createdAt | datetime | Timestamp when this license was created. |
| creatorId | integer | Id of the user who created this license. |
| customerId | integer | Id of the customer this license belongs to. |
| end | integer | Optional end date of the license as Unix timestamp. |
| flag | integer | Status flag of the license. 0 = Active, 1 = Deleted, 10 = Locked. allowed values: 0110 |
| hasUsageRestrictions | boolean | If true, this license has usage restrictions. Check metadata for details. |
| id | integer | Unique identifier of the license or license template. |
| isTemplate | boolean | If true, this license is a template. |
| mediaContainerId | integer | Id of the mediaContainer this license belongs to |
| metadata | array | Array of metadata objects assigned to this license. |
| └ id | integer | Unique identifier of this metadata entry. |
| └ licenseId | integer | Id of the license this metadata belongs to. |
| └ title | string | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | Content value of this metadata entry. |
| └ language | string | Language code of this metadata entry. |
| └ flag | boolean | Flag of this metadata entry. |
| └ lastEditor | integer | Id of the user who last edited this metadata entry. |
| personalRights | boolean | If true, personal rights have been cleared for this license. |
| settings | object | Miscellaneous settings for this license. |
| └ status | object | Status settings for this license. |
| └ color | string | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | Start date of the license as Unix timestamp. |
| templateId | integer | Id of the license template this license is based on. |
| types | array | Array of usage types this license applies to. |
| updatedAt | datetime | Timestamp when this license was last updated. |
License create
POST/v5/license
Creates a new license or license template. If you create a license based on a template, the template must be locked (flag 10).
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| contacts | array | ✗ | Array of contact objects for this license. At least one contact of type "licensor" is required. |
| └ id | integer | ✗ | Unique identifier of this license-contact relation. |
| └ licenseId | integer | ✗ | Id of the license this contact belongs to. |
| └ contactId | integer | ✓ | Id of the contact. |
| └ type | string | ✓ | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | ✗ | Optional notes for this contact relation. |
| └ flag | boolean | ✗ | Flag of this contact relation. |
| └ creatorId | integer | ✗ | Id of the user who created this contact relation. |
| └ customerId | integer | ✗ | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | ✗ | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | ✗ | Timestamp when this contact relation was last updated. |
| end | integer | ✗ | Optional end date of the license as Unix timestamp. |
| hasUsageRestrictions | boolean | ✗ | Set to true to mark this license as usage restricted. Put details into the license_description metadata field. |
| isTemplate | boolean | ✗ | Set to true to create this license as a template. |
| lockLicense | boolean | ✗ | Set to true to lock the license after creation (flag 10, cannot be changed afterwards). Set to false to release the lock, which requires the unlockReason parameter. |
| mediaContainerId | integer | ✗ | Id of the mediaContainer this license is for. Leave empty when creating a template. |
| metadata | array | ✗ | Array of metadata objects for this license. At least license_name and license_description are required. |
| └ id | integer | ✗ | Unique identifier of this metadata entry. |
| └ licenseId | integer | ✗ | Id of the license this metadata belongs to. |
| └ title | string | ✓ | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | ✓ | Content value of this metadata entry. |
| └ language | string | ✓ | Language code of this metadata entry. |
| └ flag | boolean | ✗ | Flag of this metadata entry. |
| └ lastEditor | integer | ✗ | Id of the user who last edited this metadata entry. |
| personalRights | boolean | ✗ | Set to true to mark personal rights as cleared. |
| settings | object | ✗ | Miscellaneous settings for this license. |
| └ status | object | ✗ | Status settings for this license. |
| └ color | string | ✗ | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | ✗ | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | ✗ | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | ✗ | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | ✓ | Start date of the license as Unix timestamp. Not required when creating a template. |
| templateId | integer | ✗ | Id of the license template to use as basis. Template data will be merged with the sent data. The referenced template must be locked (flag 10). |
| types | array | ✗ | Array of usage types for this license or template (e.g. ["web", "tv", "print"]). |
Response
| Field | Type | Description |
|---|---|---|
| contacts | array | Array of contact objects assigned to this license. |
| └ id | integer | Unique identifier of this license-contact relation. |
| └ licenseId | integer | Id of the license this contact belongs to. |
| └ contactId | integer | Id of the contact. |
| └ type | string | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | Optional notes for this contact relation. |
| └ flag | boolean | Flag of this contact relation. |
| └ creatorId | integer | Id of the user who created this contact relation. |
| └ customerId | integer | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | Timestamp when this contact relation was last updated. |
| createdAt | datetime | Timestamp when this license was created. |
| creatorId | integer | Id of the user who created this license. |
| customerId | integer | Id of the customer this license belongs to. |
| end | integer | Optional end date of the license as Unix timestamp. |
| flag | integer | Status flag of the license. 0 = Active, 1 = Deleted, 10 = Locked. allowed values: 0110 |
| hasUsageRestrictions | boolean | If true, this license has usage restrictions. Check metadata for details. |
| id | integer | Unique identifier of the license or license template. |
| isTemplate | boolean | If true, this license is a template. |
| mediaContainerId | integer | Id of the mediaContainer this license belongs to |
| metadata | array | Array of metadata objects assigned to this license. |
| └ id | integer | Unique identifier of this metadata entry. |
| └ licenseId | integer | Id of the license this metadata belongs to. |
| └ title | string | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | Content value of this metadata entry. |
| └ language | string | Language code of this metadata entry. |
| └ flag | boolean | Flag of this metadata entry. |
| └ lastEditor | integer | Id of the user who last edited this metadata entry. |
| personalRights | boolean | If true, personal rights have been cleared for this license. |
| settings | object | Miscellaneous settings for this license. |
| └ status | object | Status settings for this license. |
| └ color | string | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | Start date of the license as Unix timestamp. |
| templateId | integer | Id of the license template this license is based on. |
| types | array | Array of usage types this license applies to. |
| updatedAt | datetime | Timestamp when this license was last updated. |
License update
PUT/v5/license/:licenseId
Updates a license or license template. The mediaContainerId and templateId cannot be changed.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| contacts | array | ✗ | |
| └ id | integer | ✗ | Unique identifier of this license-contact relation. |
| └ licenseId | integer | ✗ | Id of the license this contact belongs to. |
| └ contactId | integer | ✗ | Id of the contact. |
| └ type | string | ✓ | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | ✗ | Optional notes for this contact relation. |
| └ flag | boolean | ✗ | Flag of this contact relation. |
| └ creatorId | integer | ✗ | Id of the user who created this contact relation. |
| └ customerId | integer | ✗ | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | ✗ | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | ✗ | Timestamp when this contact relation was last updated. |
| end | integer | ✗ | Optional end date of the license as Unix timestamp. Make sure to also send start when setting an end date. |
| hasUsageRestrictions | boolean | ✗ | Set to true to mark this license as usage restricted. The description should contain details. |
| isTemplate | boolean | ✗ | Set to true to update this license as a template. |
| licenseId | integer | ✓ | Id of the license or license template to update or destroy. |
| lockLicense | boolean | ✗ | Set to true to lock the license (flag 10, cannot be changed afterwards). Set to false to release the lock, which requires the unlockReason parameter. |
| metadata | array | ✗ | |
| └ id | integer | ✗ | Unique identifier of this metadata entry. |
| └ licenseId | integer | ✗ | Id of the license this metadata belongs to. |
| └ title | string | ✓ | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | ✓ | Content value of this metadata entry. |
| └ language | string | ✓ | Language code of this metadata entry. |
| └ flag | boolean | ✗ | Flag of this metadata entry. |
| └ lastEditor | integer | ✗ | Id of the user who last edited this metadata entry. |
| personalRights | boolean | ✗ | Set to true to mark personal rights as cleared. |
| settings | object | ✗ | Miscellaneous settings for this license. |
| └ status | object | ✗ | Status settings for this license. |
| └ color | string | ✗ | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | ✗ | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | ✗ | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | ✗ | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | ✓ | Start date of the license as Unix timestamp. Not required when updating a template. |
| types | array | ✗ | Array of usage types for this license or template (e.g. ["web", "tv", "print"]). |
| unlockReason | string | ✗ | Required when setting lockLicense to false. Provide a reason for releasing the lock. |
Response
| Field | Type | Description |
|---|---|---|
| contacts | array | Array of contact objects assigned to this license. |
| └ id | integer | Unique identifier of this license-contact relation. |
| └ licenseId | integer | Id of the license this contact belongs to. |
| └ contactId | integer | Id of the contact. |
| └ type | string | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | Optional notes for this contact relation. |
| └ flag | boolean | Flag of this contact relation. |
| └ creatorId | integer | Id of the user who created this contact relation. |
| └ customerId | integer | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | Timestamp when this contact relation was last updated. |
| createdAt | datetime | Timestamp when this license was created. |
| creatorId | integer | Id of the user who created this license. |
| customerId | integer | Id of the customer this license belongs to. |
| end | integer | Optional end date of the license as Unix timestamp. |
| flag | integer | Status flag of the license. 0 = Active, 1 = Deleted, 10 = Locked. allowed values: 0110 |
| hasUsageRestrictions | boolean | If true, this license has usage restrictions. Check metadata for details. |
| id | integer | Unique identifier of the license or license template. |
| isTemplate | boolean | If true, this license is a template. |
| mediaContainerId | integer | Id of the mediaContainer this license belongs to |
| metadata | array | Array of metadata objects assigned to this license. |
| └ id | integer | Unique identifier of this metadata entry. |
| └ licenseId | integer | Id of the license this metadata belongs to. |
| └ title | string | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | Content value of this metadata entry. |
| └ language | string | Language code of this metadata entry. |
| └ flag | boolean | Flag of this metadata entry. |
| └ lastEditor | integer | Id of the user who last edited this metadata entry. |
| personalRights | boolean | If true, personal rights have been cleared for this license. |
| settings | object | Miscellaneous settings for this license. |
| └ status | object | Status settings for this license. |
| └ color | string | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | Start date of the license as Unix timestamp. |
| templateId | integer | Id of the license template this license is based on. |
| types | array | Array of usage types this license applies to. |
| updatedAt | datetime | Timestamp when this license was last updated. |
License destroy
DELETE/v5/license/:licenseId
Deletes a license or license template. Deletion is only allowed for unlocked items (flag 0). You can only destroy a license template if it's not locked an linked to a license
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| licenseId | integer | ✓ | Id of the license or license template to update or destroy. |
Response
| Field | Type | Description |
|---|---|---|
| contacts | array | Array of contact objects assigned to this license. |
| └ id | integer | Unique identifier of this license-contact relation. |
| └ licenseId | integer | Id of the license this contact belongs to. |
| └ contactId | integer | Id of the contact. |
| └ type | string | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | Optional notes for this contact relation. |
| └ flag | boolean | Flag of this contact relation. |
| └ creatorId | integer | Id of the user who created this contact relation. |
| └ customerId | integer | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | Timestamp when this contact relation was last updated. |
| createdAt | datetime | Timestamp when this license was created. |
| creatorId | integer | Id of the user who created this license. |
| customerId | integer | Id of the customer this license belongs to. |
| end | integer | Optional end date of the license as Unix timestamp. |
| flag | integer | Status flag of the license. 0 = Active, 1 = Deleted, 10 = Locked. allowed values: 0110 |
| hasUsageRestrictions | boolean | If true, this license has usage restrictions. Check metadata for details. |
| id | integer | Unique identifier of the license or license template. |
| isTemplate | boolean | If true, this license is a template. |
| mediaContainerId | integer | Id of the mediaContainer this license belongs to |
| metadata | array | Array of metadata objects assigned to this license. |
| └ id | integer | Unique identifier of this metadata entry. |
| └ licenseId | integer | Id of the license this metadata belongs to. |
| └ title | string | Title/key of this metadata entry (e.g. license_name, license_description, license_warning, etc). allowed values: license_namelicense_descriptionlicense_warninglicense_noteslicense_rightsUsageTerms |
| └ content | string | Content value of this metadata entry. |
| └ language | string | Language code of this metadata entry. |
| └ flag | boolean | Flag of this metadata entry. |
| └ lastEditor | integer | Id of the user who last edited this metadata entry. |
| personalRights | boolean | If true, personal rights have been cleared for this license. |
| settings | object | Miscellaneous settings for this license. |
| └ status | object | Status settings for this license. |
| └ color | string | RGB color triple representing the status color (e.g. "222,33,99"). |
| └ behaviour | object | Behaviour settings for this license. |
| └ ignoreAutoDeactivate | boolean | If true, the license will not be auto-deactivated. |
| └ ignoreForMediaContainerSettings | boolean | If true, this license is excluded from mediaContainer settings evaluation. |
| start | integer | Start date of the license as Unix timestamp. |
| templateId | integer | Id of the license template this license is based on. |
| types | array | Array of usage types this license applies to. |
| updatedAt | datetime | Timestamp when this license was last updated. |
License updaterelation
POST/v5/license/updateRelation
Sets relations between contacts and a license. Always send ALL relations. The existing ones will be updated if necessary, new ones will be created, items existing in database but not in payload will be removed without further warning.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| contacts | array | ✓ | Array of objects with all contacts |
| └ id | integer | ✗ | Unique identifier of this license-contact relation. |
| └ licenseId | integer | ✗ | Id of the license this contact belongs to. |
| └ contactId | integer | ✓ | Id of the contact. |
| └ type | string | ✗ | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | ✗ | Optional notes for this contact relation. |
| └ flag | boolean | ✗ | Flag of this contact relation. |
| └ creatorId | integer | ✗ | Id of the user who created this contact relation. |
| └ customerId | integer | ✗ | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | ✗ | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | ✗ | Timestamp when this contact relation was last updated. |
| licenseId | integer | ✓ | Id of the license or license template to update or destroy. |
Response
| Field | Type | Description |
|---|---|---|
| contacts | array | Array of contact objects assigned to this license. |
| └ id | integer | Unique identifier of this license-contact relation. |
| └ licenseId | integer | Id of the license this contact belongs to. |
| └ contactId | integer | Id of the contact. |
| └ type | string | Role of the contact in relation to this license. allowed values: licensorlicensee |
| └ notes | string | Optional notes for this contact relation. |
| └ flag | boolean | Flag of this contact relation. |
| └ creatorId | integer | Id of the user who created this contact relation. |
| └ customerId | integer | Id of the customer this contact relation belongs to. |
| └ createdAt | datetime | Timestamp when this contact relation was created. |
| └ updatedAt | datetime | Timestamp when this contact relation was last updated. |
| licenseId | integer | Id of the license or license template to update or destroy. |