Content Access System for Aggregators

Overview

This document explains how content access works in Publica.la for aggregator partners who distribute content to multiple sub-tenants and manage user subscriptions via API.

---

Glossary

Term	Definition
Content	Any item that can be accessed by users (ebooks, audiobooks, etc.). You may see it referred to as: "issues", "publications", or "products".
Plan	A subscription offering that grants access to specific content or collections of content.
Collection	A group of content items. Plans grant access to one or more collections.
Tenant	An isolated workspace representing a store or library. Each tenant has its own users, inventory, plans, and configurations.
Aggregator	A parent tenant that owns and distributes content to multiple sub-tenants (stores/libraries).
Order	A record linking a user to a plan, created via the Orders API.
Auth Token	The authentication mechanism for users coming from external systems. See Authentication Token.

---

Key Concepts

1. Tenant Hierarchy: Aggregator & Sub-tenants

• Aggregator Tenant: The parent tenant that owns and distributes content to multiple sub-tenants. The aggregator uploads content via API and explicitly shares it with specific sub-tenants.

• Sub-tenants (Stores/Libraries): Child tenants that receive shared content from the aggregator. Each sub-tenant has:

  • Its own isolated inventory (content received from the aggregator)
  • Its own Users
  • Its own Plans (subscription offerings)
  • Its own Collections and Keywords

2. Content

• Content represents a single publication (ebook, audiobook, etc.). When the owner modifies metadata or files, changes apply immediately to all tenants that have it in their inventory.
• Each sub-tenant has its own isolated inventory. When an aggregator shares content, the sub-tenant receives it in their inventory with properties inherited from the original.
• Sub-tenants can organize shared content using:
  • Collections: Groups of content used in subscription plans
  • Keywords: For search and discovery

3. Collections

Collections are groups of content. They serve as the bridge between Plans and content:

• A Collection can contain multiple content items
• A content item can belong to multiple Collections
• Plans grant access to one or more Collections
• Collections are created when first assigned to a content item

4. Plans & Subscriptions

• Plan: A subscription offering that grants access to specific Collections
• Plans in this model use assigns_collections = true (collection-based access, not full catalog)
• Subscriptions are assigned to users via the Orders API

5. Orders API

The Orders API v3 is used to create subscriptions. When an order is created for a user with a specific plan, that user gains access to all content in the plan's associated collections.

---

End-to-End Flow

Part A: Setup & Configuration (Async - Aggregator Controlled)

These phases happen asynchronously, before any user accesses content. They are controlled by the aggregator and sub-tenant administrators.

---

Phase 1: Content Distribution (Aggregator → Sub-tenants)

1. Aggregator uploads content via API to their tenant
2. Aggregator shares content explicitly to specific sub-tenants via API
3. Sub-tenant receives the content in their isolated inventory
4. Content properties are inherited from the original (title, files, metadata, etc.)

Phase 2: Plan & Collection Setup (Sub-tenant Configuration)

1. Sub-tenant assigns Collections to content (Collections are created automatically when first assigned)
2. Sub-tenant creates Plans that grant access to specific Collections
3. Plan configuration includes:
   • Which Collections are included
   • Pricing (or no pricing for API-assigned plans)
   • Duration (recurring, prepaid, etc.)

Phase 3: Subscription Assignment (Orders API)

1. External system calls Orders API v3 to assign a user to a Plan
2. If user doesn't exist, the system creates the user automatically
3. If user already exists, the subscription is simply assigned
4. Order is created linking User → Plan
5. User now has a subscription that grants access to the Plan's Collections

---

Part B: User Access (Real-time - User Triggered)

These phases happen in real-time when the user accesses the platform.

---

Phase 4: User Authentication & Content Access

1. User authenticates via Auth Token from external system
2. User already has their subscription assigned (from Phase 3)
3. User can access content in their Plan's Collections

Phase 5: Content Access Verification

When a user tries to read content:

1. System checks if user has an active subscription (Order)
2. System retrieves the Collections associated with the Plan
3. System checks if the content belongs to any of those Collections
4. If match found → Access granted (reason: SUBSCRIPTION_WITH_COLLECTIONS)
5. If no match → Access denied (or check other access methods)

---

Flow Diagrams

Complete End-to-End Flow

Access Decision Tree

Data Relationships

---

Access Methods

While subscription-to-collections is the primary model for aggregator integrations, other access methods exist. The table below shows all access methods, their API codes (used in reading reports), and additional context.

Method	API Code	Description	Report Data
Free Content	free_issue	Content marked as free, accessible to all	-
Free Access (Tenant)	free_access	Tenant-wide free access enabled	-
Collection Subscription	subscription_with_collections	User's plan includes this collection	plan_id
Full Catalog Subscription	global_subscription	Plan with all_content = true grants everything	plan_id
Retail Purchase	bought_issue	User bought the individual content	-
Manual Assignment	assigned_issue	Admin assigned the content directly to user	-
Gift	gifted_issue	User received this as a gift	-
Administrator	administrator_user	User is an admin (full access)	-
External Permissions	external_permissions	Custom scope for external integrations	scope details
PPU (Pay-Per-Use)	license_ppu	Temporary loan-based access	loan details
Preview	preview_issue	Preview access	-
LTI Integration	lti_and_entry_point_free_access	LTI integration access	-
SAML Integration	saml_and_entry_point_free_access	SAML integration access	-
External Collection Sub.	external_subscription_with_collections	External subscription with collections	plan_id
External Global Sub.	external_global_subscription	External global subscription	plan_id

Access Reasons in Reading Reports

When a user reads content, the system tracks the reason for access. This information appears in the reading reports (analytics) provided by the Coniglio service. Each reading session includes:

• reason_type: The API Code from the table above
• reason_value: Additional context (e.g., the plan_id that granted access)

---

See Also

• Orders API v3 Overview
• Authentication Token
• Content API v3