Path parameters

• id string Required

  System ID

Responses

• 201 application/json

  Entitlement created successfully

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object

    One add-on grant for one system, optionally narrowed to a single application instance via scope (omitted = whole system). active is derived: not revoked and not expired (valid_until null = perpetual). Revocation is soft (sets revoked_at, the row is kept for audit).

    Hide data attributes Show data attributes object

    • id string(uuid)

      Grant ID

    • system_id string

      ID of the system the grant belongs to

    • entitlement string

      Catalog id of the granted add-on

    • scope string

      Application instance the grant is narrowed to (only for scoped catalog items). Omitted = whole system.

    • source string

      How the grant was created

      Values are manual, shop, or legacy-import.

    • source_ref string

      Free-form reference to the originating record (e.g. shop subscription id)

    • valid_from string(date-time)

      When the grant became valid

    • valid_until string(date-time) | null

      Expiry of the grant. Null = perpetual.

    • revoked_at string(date-time) | null

      When the grant was revoked. Null = not revoked.

    • revoked_source string

      Who revoked the grant: manual (admin via API/UI — deliberate, the shop button is not offered again) or shop (deactivate webhook: subscription cancelled or payment failed — buyable again). Omitted when not revoked.

      Values are manual or shop.

    • active boolean

      Derived: not revoked and not expired

    • pending_ref string

      Shop order placed at checkout and not yet paid (display-only; cleared by activate or cancel). Omitted when nothing is pending.

    • pending_since string(date-time) | null

      When the pending order was placed

    • status string

      Server-computed lifecycle status. suspended = the grant is intact but the owning system (or its organization) is suspended or deleted, so collect rejects its credentials. pending = an order is awaiting payment (masks revoked/expired but never an active grant). Enforcement authorizes only truly active grants.

      Values are active, expired, revoked, suspended, or pending.

    • created_by object

      Snapshot of the user who created the grant or availability rule

      Hide created_by attributes Show created_by attributes object

      • user_id string

        Logto ID of the creator

      • user_name string

        Full name of the creator

      • organization_id string

        Organization ID of the creator

      • organization_name string

        Organization name of the creator

      • channel string

        Set to "shop" when the grant was created via POST /entitlements/activate. Omitted otherwise.

    • purchased_by object

      Audit snapshot of the my user that BOUGHT the grant on the shop, resolved from the order's customer email (webhook activation, or the legacy-import backfill when the expiry map carries the order email) and frozen at purchase time (robust to later renames/moves). Omitted for manual grants and legacy rows without an order. When the email matches no my user only email is present. When the buyer's organization is outside the viewer's hierarchy the snapshot is redacted to {out_of_scope: true} (owner org and Super Admin always see it in full).

      Hide purchased_by attributes Show purchased_by attributes object

      • logto_id string

        Logto ID of the buyer

      • name string

        Full name of the buyer at purchase time

      • email string

        Email of the buyer (the shop order's customer)

      • organization_id string

        Logto ID of the buyer's organization at purchase time

      • organization_name string

        Name of the buyer's organization at purchase time

      • org_role string

        Hierarchy role of the buyer's organization at purchase time

      • user_roles array[string]

        User role names of the buyer at purchase time

      • out_of_scope boolean

        Present (true) when the buyer identity was redacted because it is outside the viewer's hierarchy

    • variant object

      Shop variation (tier) of the purchased product line. Display metadata only: the add-on↔product mapping stays on the parent product and /auth enforcement ignores it. Refreshed by activate, so tier upgrades/downgrades follow the renewals. Omitted for manual grants and simple (non-variable) products.

      Hide variant attributes Show variant attributes object

      • id integer

        WooCommerce variation id

      • sku string

        SKU of the variation

      • label string

        Human-readable tier, from the variation attributes

    • renewal_count integer

      Paid shop orders on this grant beyond the first: activate increments it when source_ref changes (webhook retries on the same order never double-count). 0 = first period.

    • created_at string(date-time)
    • updated_at string(date-time)
• 400 application/json

  Unknown entitlement, scope not supported by the catalog item, invalid source, or system-type mismatch ("this entitlement applies to nsec systems only")

  Hide response attributes Show response attributes object

  • code integer

    HTTP error code

  • message string

    Error message

  • data object
    Hide data attributes Show data attributes object

    • type string

      Type of error

      Values are validation_error or external_api_error.

    • errors array[object]
      Hide errors attributes Show errors attributes object

      • key string

        Field name that failed validation

      • message string

        Error code or message

      • value string

        Value that failed validation

    • details

      Additional error details

• 401 application/json

  Unauthorized - invalid or missing token

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null
• 403 application/json

  Forbidden - insufficient permissions

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null
• 404 application/json

  Resource not found

  Hide response attributes Show response attributes object

  • code integer

    HTTP error code

  • message string

    Error message

  • data object
    Hide data attributes Show data attributes object

    • type string

      Type of error

      Values are validation_error or external_api_error.

    • errors array[object]
      Hide errors attributes Show errors attributes object

      • key string

        Field name that failed validation

      • message string

        Error code or message

      • value string

        Value that failed validation

    • details

      Additional error details

• 409 application/json

  Grant already exists for this (system, entitlement, scope)

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null
• 500 application/json

  Internal server error

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null