Guides

API call specifications for entitlements

This article provides API details for the Cortex entitlements service.

Introduction

Cortex provides an entitlements service to enable gating of content, with access granted to fans based on a purchase made via a third party platform, or other events.

Public APIs

The following API does not require any authentication and can be used to list active products.

Get active products

The following endpoint outputs a list of active product objects.

GET {base URL}/v1/public/{client ID}/products

In which:

{base URL} is the URL shown below, depending on environment used.

{client ID} is your client ID, assigned during onboarding.

Query parameters

entitlementIds (string, optional): Comma-separated list of entitlement IDs. For example https://entitlements-management-system.cortextech.io/v1/public/DEMO/products?entitlementIds=Id1,Id2. If provided, the list is filtered to provide products that contain at least one of the specified entitlements.

cURL example

curl -X GET "https://entitlements-management-system.cortextech.io/v1/public/DEMO/products?entitlementIds=id1,id2"

User APIs

The following APIs require authentication by providing a valid token. As such, they can be used by fan-facing applications in which the fan has logged in.

Get user entitlements

The following endpoint outputs a list of entitlements associated to the logged-in fan.

This is the primary endpoint used by client applications to check that the fan has access to gated content in which an entitlement is a requirement to view the content.

GET {base URL}/v1/entitlements

In which {base URL} is as described above

Query parameters

active (bool, optional): Filter by active status. active=true filters for entitlements that are currently within their start/end date range and have active: true. Defaults to true.

sourceSystem (string[], optional): Filter by source systems.

cURL example

curl -X GET "https://entitlements-management-system.cortextech.io/v1/entitlements" \
     -H "Authorization: Bearer <token>"

APIs requiring an API key

The following APIs require an API key provided as an X-API-Key header. API keys can be provided by Cortex on request. These endpoints are typically used to manage entitlements of a fan such as by setting, removing or refreshing a fan's entitlement.

Get user entitlements

The following endpoint outputs a list of entitlements associated to a specified fan.

It returns entitlements assigned directly or via products.

GET {base URL}/v1/admin/external/users/USERID/entitlements

In which:

{base URL} is as described above

USER ID is the auth ID representing the user or fan, as per Cortex SSO.

Query parameters

active (bool, optional): Filter by active status. active=true filters for entitlements that are currently within their start/end date range and have active: true.

sourceSystem (string[], optional): Filter by source systems.

page (int, optional): Page number. Defaults to 0.

size (int, optional): Items per page. Defaults to 50.

sort (string, optional): Sort field (e.g., -startDate). Defaults to -startDate

cURL example

curl -X GET "https://entitlements-management-system.cortextech.io/v1/admin/external/users/123/entitlements?active=true&sourceSystem=INCROWD_VM" \
     -H "X-API-Key: your_api_key"

Set user entitlements

The following endpoint can be used to grant an entitlement to a specified fan.

POST {base URL}/v1/admin/external/users/USER ID/entitlements

In which

{base URL} and USER ID are as described above

Body (JSON) includes details of the entitlement, in the format shown below.

{
  "entitlements": [
    {
      "entitlementId": "string",
      "startDate": "ISO8601",
      "endDate": "ISO8601 (optional)",
      "active": "bool (optional)",
      "metadata": {
        "sourceSystem": "string",
        "sourceSystemId": "string",
        "sourceSystemUserId": "string",
        "productId": "string"
      }
    }
  ]
}

Note: This is an additive operation. If a duplicate entitlement (same user, ID, and source metadata) exists, it will return a 409 Conflict.

cURL example

curl -X POST "https://entitlements-management-system.cortextech.io/v1/admin/external/users/123/entitlements" \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"entitlements": [{"entitlementId": "60f7e...f8", "startDate": "2023-01-01T00:00:00.000Z"}]}'

Outputs

{"data": {"set": 1}}

Remove user entitlements

The following endpoint can be used to remove an entitlement from a specified fan.

DELETE {base URL}/v1/admin/external/users/USER ID/entitlements

In which

{base URL} and USER ID are as described above

Body (JSON) provides entitlement IDs representing the entitlements to be removed.

{
  "entitlementIds": ["string"]
}

cURL example

curl -X DELETE "https://entitlements-management-system.cortextech.io/v1/admin/external/users/123/entitlements" \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"entitlementIds": ["60f7e...f8"]}'

Outputs

{"data": {"removed": 1}}

Refresh user entitlements (upsert)

The following endpoint can be used to refresh a fan's entitlement. It first deactivates all existing user entitlement records matching the provided entitlement IDs for that fan, then creates or updates them with the new data.

PUT {base URL}/v1/admin/external/users/USERID/entitlements

In which

{base URL} and USER ID are as described above

Body (JSON) is the same as for the Set user entitlements endpoint - see above.

cURL example

curl -X PUT "https://entitlements-management-system.cortextech.io/v1/admin/external/users/123/entitlements" \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"entitlements": [{"entitlementId": "60f7e...f8", "startDate": "2023-01-01T00:00:00.000Z"}]}'

Outputs

{"data": {"upserted": 1}}

List all entitlements

The following endpoint fetches a list of all entitlements available to the client associated with the API key.

GET {base URL}/v1/admin/external/entitlements

In which

{base URL} is as described above

Query parameters

active (bool, optional): Filter by active status. active=true filters for entitlements that currently have status set to active.

sourceSystem (string[], optional): Filter by source systems.

page (int, optional): Page number. Defaults to 0.

size (int, optional): Items per page. Defaults to 50.

sort (string, optional): Sort field

cURL example

curl -X GET "https://entitlements-management-system.cortextech.io/v1/admin/external/entitlements?active=true" \
     -H "X-API-Key: your_api_key"

Get entitlement details

The following endpoint returns details of a single specified entitlement.

GET {base URL}/v1/admin/external/entitlements/{ID}

In which

{base URL} is as described above

{ID} is the entitlement ID for which details are required.

cURL example

curl -X GET "https://entitlements-management-system.cortextech.io/v1/admin/external/entitlements/60f7e...f8" \
     -H "X-API-Key: your_api_key"

Updated 22 days ago

Did this page help you?