External Principal and Scope Model

This document defines how integrations are represented, scoped, and authorized inside Tov+.

2 min read

Purpose

This document defines how integrations are represented, scoped, and authorized inside Tov+.

External principal model

`integration_principal`

Represents:

a non-human external application or partner system

Backed by:

integration app record
active credential
explicit scope grants

Authorization inputs:

principal type
integration id
credential id
occasion/event/module/resource scope
allowed actions

Identity representation

Each integration principal should be represented by:

integration_app_id
display_name
integration_category
environment
status

Optional additional references:

partner organization id
owning occasion id for narrowly scoped partner connections

Credential representation

Credential metadata should include:

credential_id
key_id
status
created_at
last_used_at
expires_at
revoked_at

Rules:

raw secrets are not the long-term source of truth in logs or UI
one integration may have multiple credentials for rotation windows

Scope model

Scope dimensions

Every integration scope should express:

allowed action
allowed resource family
allowed scope level
optional occasion constraint
optional event constraint
optional module constraint
optional resource constraint

Supported scope levels

platform
occasion
event
module_installation
module_enablement
resource

Examples

printer integration: read on published_artifact at occasion scope, narrowed to printable module resources
venue integration: read on seating_plan at event scope
caterer integration: read on dietary summary resource at event scope

Authorization model

Integration authorization should follow the same general sequence as other principals:

authenticate credential
resolve integration principal
resolve target scope
evaluate allowed actions and resource constraints
allow or deny with audit trail

Rules:

no integration request bypasses the central authorization engine
integration grants are explicit, not inferred from partner category alone

Scope assignment patterns

Occasion-scoped partner integration

Use when:

the partner supports one occasion or a small set of specific occasions

Examples:

printer for one wedding
caterer for one event weekend

Event-scoped partner integration

Use when:

the partner should only see one event or one event family

Examples:

venue for reception only
caterer for dinner event only

Platform-scoped service integration

Use when:

Tov+ uses an infrastructure service across many occasions

Examples:

messaging provider
object storage/media provider

Rule:

platform-scoped service integrations still should not read arbitrary product data unless needed

Resource restrictions

Integrations may need resource-specific restrictions beyond scope level.

Examples:

only assets attached as published artifacts
only seating plans in published state
only communication summaries, not raw messages

Recommended approach:

model these restrictions as explicit resource/action grants or adapter-level allowlists backed by grants

Expiration and review expectations

Recommended controls:

optional integration connection expiration
credential rotation deadlines
periodic access review for partner integrations
disable or archive dormant integrations

Audit expectations

Every integration request or delivery should record:

integration id
credential id
action
resolved scope
decision
timestamp
correlation id

Final summary

The external principal model treats every integration as a scoped machine principal with explicit credentials and grants. Scope is multidimensional across action, resource family, and occasion/event/module/resource boundaries, and authorization always flows through the same central permission model rather than category-based trust.