> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myme.so/llms.txt
> Use this file to discover all available pages before exploring further.

# System types

> Platform-internal operational items — devices, credentials, webhooks, app identities

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

## The set

| Type                 | Represents                                                                                                                                                                                                                                                                                                | Surfaces in console as                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `system.device`      | A connected device. Carries name, kind, last-active timestamp.                                                                                                                                                                                                                                            | A Devices list. Revocable.                                                       |
| `system.credential`  | A platform credential — discriminated on `kind`: `api_key` (a Marfa client credential), `oauth_token` (encrypted OAuth provider config for an Integration), or `api_token` (encrypted bearer for an Integration whose upstream is API-key-authenticated, not OAuth). Carries permissions, last-used time. | A Credentials list. Revocable.                                                   |
| `system.webhook`     | A webhook subscription. Carries URL, filters, delivery history.                                                                                                                                                                                                                                           | A Webhooks list. Editable.                                                       |
| `system.app`         | A registered app identity. Required for `app.<app-name>.<type>` to mean anything.                                                                                                                                                                                                                         | An Apps list.                                                                    |
| `system.connection`  | An approved relationship between this space and an external authority. Three kinds: `app`, `integration`, `tenant`. See [Connections](/concepts/connections).                                                                                                                                             | A Connections list. Revocable.                                                   |
| `system.profile`     | The signed-in user's account profile — username, name, bio, avatar. One per account, served via `/profile/me`. See [Profile](/concepts/profile).                                                                                                                                                          | An account-settings page.                                                        |
| `system.integration` | A published manifest describing how a connector talks to an external service. One item per (name, version) pair. See [Integrations](/concepts/integrations).                                                                                                                                              | An Integrations list — typically the marketplace surface.                        |
| `system.activity`    | Operator-visible state — sync progress, errors, reauthorisation prompts. Severity-tagged. See [Activity](/concepts/activity).                                                                                                                                                                             | An Activity feed; the `action_required` slice surfaces as a Repairs-style inbox. |

## 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:

```
GET /items?type=system.connection
GET /items?type=system.connection&include=system
GET /items?type=system.integration
GET /items?type=system.webhook
GET /items?type=system.device
```

Standard items semantics apply — pagination, filters, edge / metadata hydration, audit. The same applies to single-item GET, PATCH, and `transition`. See [Search and query](/api/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.