Skip to main content
system.* is a small reserved namespace for operational items. Only the platform defines these types; spaces and apps cannot register new ones.

​
The set

​
Listing system items

Every system.* type is listed through the items route. There is no GET /connections, GET /webhooks, or GET /integrations for retrieving the rows — those root paths exist for install / uninstall / proxy operations on the kind, not for listing. To enumerate them, query the items route with the type filter:
Standard items semantics apply — pagination, filters, edge / metadata hydration, audit. The same applies to single-item GET, PATCH, and transition. See Search and query for the filter grammar. The include=system parameter is only needed when a query already carries system.* types but the result-set bias still excludes them — see the next section.

​
Items with reduced operability

system.* items are items, so they share the standard item plumbing — they’re listable, addressable, audit-logged. The web console can render lists for them through ordinary item views without bespoke pages. But they are not user content, and several universal operations don’t apply:
  • Excluded from search defaults. GET /search and GET /items (with no type filter) skip system.* rows. Consumers opt in explicitly.
  • No tier dimension. system.* items don’t carry the tier field. Setting it on write returns 400 invalid_field.
  • Bounded lifecycle. system.* items use only active and revoked — not the universal three-state (active / archived / trashed). The transition endpoint enforces this.
  • Platform-only registration. Only Marfa-platform credentials can register system.* types. Ordinary credentials with register types permission cannot.
This is a recurring pattern — “item with reduced operability” — and any future system.* types will follow the same shape.

​
Why items, not bespoke pages

Treating these as items rather than special-cased records means the web console gets device, credential, webhook, and app management for free through the same surfaces it uses for everything else. Listings, filters, audit logs, search, permissions — all work uniformly. The trade-off is that some universal operations have to be carved out (tier, archive). The carve-outs are small. The reuse is large.

​
Permissions

system.* permissions are scoped per type: a credential can hold read system.device without read system.credential. The console uses this to expose, say, a Devices list to a user-level credential while keeping credential management admin-only. A non-platform credential can never write to system.*. The reserved-root check at POST /items rejects ordinary clients.

​
Naming pattern

The single segment after system. is a singular operational noun. New system.* types — when added — follow the same shape.