API 參考

Entitlements

Management API: GET /sites/{id}/entitlements, POST /sites/{id}/entitlements, GET /sites/{id}/entitlements/check, …

這頁只有英文版。API 參考、Webhook 事件與變更紀錄維持英文，和程式碼裡的欄位名稱、錯誤碼一致。

Base URL https://app.kanorio.com/api/v1Errors Pagination

List entitlements

GET/sites/{id}/entitlements

betacustomers:viewdefault (120/minute per token)

List entitlements (who can access which deliverable or featureKey) filtered by contact, deliverable or featureKey; includes revoked and expired rows. Newest first. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, INVALID_CURSOR.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
limitinteger · query
Maximum number of items to return, 1–100. Defaults to 20.
cursorstring · query
Opaque cursor from the previous page's nextCursor. Omit for the first page.
contactIdstring · query
deliverableIdstring · query
Deliverable id. Get it from deliverables.list.
featureKeystring · query
activeOnlyboolean · query
Only rows that are not revoked and not expired.

Response 200

dataobject[]required
data[].idstringrequired
data[].contactIdstringrequired
data[].deliverableIdstring | nullrequired
data[].unitIdstring | nullrequired
data[].featureKeystring | null
Commercial feature key for feature-only grants (no deliverable), e.g. "premium". For deliverable-backed entitlements the feature keys come from Deliverable.grants and this field is null.
data[].tierIdstring | nullrequired
data[].productIdstring | nullrequired
Source product snapshot when the entitlement came from an order.
data[].sourcestringrequired
ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE, EXTERNAL (payment collected outside Kanorio), GIFT.
data[].sourceRefstring | nullrequired
data[].startsAtstring | nullrequired
data[].endsAtstring | nullrequired
data[].revokedAtstring | nullrequired
data[].revokeReasonstring | nullrequired
data[].createdAtstringrequired
hasMorebooleanrequired
True when another page exists; pass nextCursor to fetch it.
nextCursorstring | nullrequired
Cursor for the next page, or null on the last page.

Errors

FORBIDDEN 403
DELIVERABLE_NOT_FOUND 404
INVALID_CURSOR 400

MCP tool entitlements_list

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/entitlements" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "data": [
    {
      "id": "ent_example01",
      "contactId": "contact_example01",
      "deliverableId": "dlv_example01",
      "unitId": null,
      "featureKey": null,
      "tierId": null,
      "productId": null,
      "source": "MANUAL_GRANT",
      "sourceRef": null,
      "startsAt": "2026-10-01T02:30:00.000Z",
      "endsAt": null,
      "revokedAt": null,
      "revokeReason": null,
      "createdAt": "2026-10-01T02:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Grant an entitlement

POST/sites/{id}/entitlements

betacustomers:managedefault (120/minute per token)Idempotency-Key

Grant a contact access to a deliverable and/or a commercial featureKey without a Kanorio purchase (gift, corporate seat, paid newsletter subscriber, or a payment collected by your own checkout). Idempotent: pass idempotencyKey to make retries return the same entitlement; with source EXTERNAL, sourceRef (your transaction id) also dedupes per deliverable, and a revoked external grant is never re-created by a replay. source EXTERNAL is only accepted from agent tokens (PAT / OAuth), never from a browser session; it requires sourceRef. Kanorio Checkout does not need to be enabled. Errors: FORBIDDEN, CONTACT_NOT_FOUND, DELIVERABLE_NOT_FOUND (archived deliverables cannot be granted), VALIDATION.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
Idempotency-Keystring · header
Client-chosen key (1-200 chars). Retrying with the same key and the same body returns the original result; the same key with a different body is rejected with IDEMPOTENCY_CONFLICT (409). Keys expire after 24 hours.

Request body

contactIdstringrequired
Get it from contacts.list or contacts.add.
deliverableIdstring
Deliverable id. Provide deliverableId and/or featureKey.
featureKeystring
Commercial feature key (e.g. "premium") matched by collection accessPolicy and entitlements.check.
endsAtstring | null
Access expiry; omit for permanent access.
source"MANUAL_GRANT" | "GIFT" | "EXTERNAL"
Why access is granted. MANUAL_GRANT (default) or GIFT for site-owner grants; EXTERNAL when the payment was collected outside Kanorio (requires sourceRef; agent tokens only).
sourceRefstring
Your system's reference for this grant (e.g. external transaction id). Used for deduplication and shown in the audit trail.
idempotencyKeystring
Client-chosen key; the same key on the same site always returns the same entitlement.

Response 201

idstringrequired
contactIdstringrequired
deliverableIdstring | nullrequired
unitIdstring | nullrequired
featureKeystring | null
Commercial feature key for feature-only grants (no deliverable), e.g. "premium". For deliverable-backed entitlements the feature keys come from Deliverable.grants and this field is null.
tierIdstring | nullrequired
productIdstring | nullrequired
Source product snapshot when the entitlement came from an order.
sourcestringrequired
ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE, EXTERNAL (payment collected outside Kanorio), GIFT.
sourceRefstring | nullrequired
startsAtstring | nullrequired
endsAtstring | nullrequired
revokedAtstring | nullrequired
revokeReasonstring | nullrequired
createdAtstringrequired

Errors

FORBIDDEN 403
CONTACT_NOT_FOUND 404
DELIVERABLE_NOT_FOUND 404 · archived deliverables cannot be granted
VALIDATION 400

MCP tool entitlements_grant

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/entitlements" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"contact_example01","deliverableId":"dlv_example01"}'

Response

{
  "id": "ent_example01",
  "contactId": "contact_example01",
  "deliverableId": "dlv_example01",
  "unitId": null,
  "featureKey": null,
  "tierId": null,
  "productId": null,
  "source": "MANUAL_GRANT",
  "sourceRef": null,
  "startsAt": "2026-10-01T02:30:00.000Z",
  "endsAt": null,
  "revokedAt": null,
  "revokeReason": null,
  "createdAt": "2026-10-01T02:30:00.000Z"
}

Entitlement check

GET/sites/{id}/entitlements/check

betacustomers:viewdefault (120/minute per token)

Check whether a contact can access a deliverable, a single unit, or a commercial featureKey right now (entitlement, free preview, release schedule, expiry). Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, VALIDATION.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
contactIdstring · queryrequired
deliverableIdstring · query
Deliverable id. Get it from deliverables.list.
unitIdstring · query
Unit id. Get it from deliverables.get.
featureKeystring · query
Commercial feature key (e.g. "premium") checked by ContentCollection.accessPolicy.

Response 200

grantedbooleanrequired
reason"entitlement" | "preview" | "none" | "not_released" | "expired" | "hidden" | "prerequisite" | "not_found"required
prerequisite: blocked by the course's require-in-order rule (lockedByUnitId is the unit to finish first).
availableAtstring | nullrequired
lockedByUnitIdstring | nullrequired
When reason is prerequisite: the unit the learner must complete first.

Errors

FORBIDDEN 403
DELIVERABLE_NOT_FOUND 404
VALIDATION 400

MCP tool entitlements_check

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/entitlements/check?contactId=contact_example01&deliverableId=dlv_example01" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "granted": true,
  "reason": "entitlement",
  "availableAt": null,
  "lockedByUnitId": null
}

Revoke an entitlement

POST/sites/{id}/entitlements/{entitlementId}/revoke

betacustomers:managedefault (120/minute per token)

Revoke one entitlement (learner loses access immediately; the row is kept for audit). Errors: FORBIDDEN, ENTITLEMENT_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
entitlementIdstring · pathrequired

Request body

reasonstring

Response 200

idstringrequired
contactIdstringrequired
deliverableIdstring | nullrequired
unitIdstring | nullrequired
featureKeystring | null
Commercial feature key for feature-only grants (no deliverable), e.g. "premium". For deliverable-backed entitlements the feature keys come from Deliverable.grants and this field is null.
tierIdstring | nullrequired
productIdstring | nullrequired
Source product snapshot when the entitlement came from an order.
sourcestringrequired
ORDER_LINE, MANUAL_GRANT, PREPAID_REDEMPTION, FREE, EXTERNAL (payment collected outside Kanorio), GIFT.
sourceRefstring | nullrequired
startsAtstring | nullrequired
endsAtstring | nullrequired
revokedAtstring | nullrequired
revokeReasonstring | nullrequired
createdAtstringrequired

Errors

FORBIDDEN 403
ENTITLEMENT_NOT_FOUND 404

MCP tool entitlements_revoke

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/entitlements/{entitlementId}/revoke" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Corporate seat reassigned"}'

Response

{
  "id": "ent_example01",
  "contactId": "contact_example01",
  "deliverableId": "dlv_example01",
  "unitId": null,
  "featureKey": null,
  "tierId": null,
  "productId": null,
  "source": "MANUAL_GRANT",
  "sourceRef": null,
  "startsAt": "2026-10-01T02:30:00.000Z",
  "endsAt": null,
  "revokedAt": "2026-10-06T08:00:00.000Z",
  "revokeReason": "Corporate seat reassigned",
  "createdAt": "2026-10-01T02:30:00.000Z"
}