Platform concepts and identities

A glossary of tenant, merchant, human roles, apps, installations, tokens, webhooks, and review concepts.

Platform concepts and identities

These terms describe different trust domains. Do not collapse a human role, a platform-staff role, and an app scope into one permission model.

Commerce and tenancy

Tenant: the enforced data boundary for one merchant organization.
Merchant: the organization operating a store inside a tenant.
Store: the merchant's commerce surface and configuration within that tenant.
User: an authenticated human identity; access still depends on membership or platform-staff authorization.

Owner: highest merchant role for the tenant and permitted to install or revoke apps.
Admin: delegated merchant administrator who may also install or revoke apps.
Staff: merchant team member with narrower business permissions; not an app installer in the current lifecycle.

Support: platform staff with read-only Marketplace review visibility.
Super Admin: platform staff authorized for review decisions and publication. This role is not a merchant credential and is not an app scope.

Developer: an external publisher identity, separate from merchant membership.
App: the stable Marketplace identity and listing owned by a developer account.
App Version: an immutable review target containing a semantic version, exact redirects, requested scopes, webhook declarations, and release notes.
Installation: the tenant-specific grant pinned to one app and one exact published version.
Scope: a named least-privilege permission requested by a version and explicitly granted by a merchant.

Access token: a short-lived bearer credential bound to an active installation and its grants.
Refresh token: a rotating credential used server-side to obtain a new token pair.
Webhook: a signed HTTPS delivery attempt to an app endpoint.
Event: a stable event ID, type, occurrence time, and payload queued for matching subscriptions.

API version: the public HTTP contract version in the path; current is /api/v1.
Marketplace review: a per-app-version approval process performed by platform staff before publication. The current pipeline is partial and will receive stronger validation later.

Platform concepts and identities

A glossary of tenant, merchant, human roles, apps, installations, tokens, webhooks, and review concepts.

These terms describe different trust domains. Do not collapse a human role, a platform-staff role, and an app scope into one permission model.

Tenant: the enforced data boundary for one merchant organization.
Merchant: the organization operating a store inside a tenant.
Store: the merchant's commerce surface and configuration within that tenant.
User: an authenticated human identity; access still depends on membership or platform-staff authorization.

Owner: highest merchant role for the tenant and permitted to install or revoke apps.
Admin: delegated merchant administrator who may also install or revoke apps.
Staff: merchant team member with narrower business permissions; not an app installer in the current lifecycle.

Support: platform staff with read-only Marketplace review visibility.
Super Admin: platform staff authorized for review decisions and publication. This role is not a merchant credential and is not an app scope.

Developer: an external publisher identity, separate from merchant membership.
App: the stable Marketplace identity and listing owned by a developer account.
App Version: an immutable review target containing a semantic version, exact redirects, requested scopes, webhook declarations, and release notes.
Installation: the tenant-specific grant pinned to one app and one exact published version.
Scope: a named least-privilege permission requested by a version and explicitly granted by a merchant.

Access token: a short-lived bearer credential bound to an active installation and its grants.
Refresh token: a rotating credential used server-side to obtain a new token pair.
Webhook: a signed HTTPS delivery attempt to an app endpoint.
Event: a stable event ID, type, occurrence time, and payload queued for matching subscriptions.

API version: the public HTTP contract version in the path; current is /api/v1.
Marketplace review: a per-app-version approval process performed by platform staff before publication. The current pipeline is partial and will receive stronger validation later.