# Plugin

object type

A Plugin — a third-party extension's DECLARATION record on the canned-pool selection pattern: the group registers the plugin ONCE, each org ENABLES it via an OrgPlugin selection. Extensions run OUT-OF-PROCESS on the developer's own infrastructure — never in-process here. The record declares what the integration IS: the least-privilege descriptor scopes (the ApiKey grammar, allow-only — the CONTRACT the merchant mints a key against; descriptive at v1, the marketplace's automated mint-flow consumes it later), an optional bound ApiKey identity (validated live in-group at write; informational v1), and its event feed — which rides REAL WebhookSubscription rows carrying pluginId (never a mirrored field). uiSlots is deliberately ABSENT until the office slot system exists (the staged-realization boundary, map d.11). ≤64 per group; doom is gate-protected: a non-doomed OrgPlugin selection OR an un-doomed bound WebhookSubscription blocks it. NOT searchable (integration config).

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (PN-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `Plugin` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: active \| inactive \| doomed. |
| `parentId` | [ID](/types/#scalars) `ID!` | The parent = the org GROUP (the selection-master law); parentId === rootId always. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/RefCaption/) `[RefCaption!]!` | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
| `developerName` | [String](/types/#scalars) | The developer/publisher display name (informational — the marketplace listing byline seed). |
| `homepageUrl` | [String](/types/#scalars) | The developer homepage (https by shape; informational — NOT a delivery target: the egress law lives on WebhookSubscription.targetUrl alone). |
| `requiredScopes` | [RoleDescriptor](/types/RoleDescriptor/) `[RoleDescriptor!]!` | The declared least-privilege scope set (the ApiKey grammar rows, ALLOW-only, deduped; 0..800 — a webhook-only plugin legally declares none). Descriptive v1; editable BY DESIGN (a declaration carries no authority — the disclosed ApiKey-immutability contrast). |
| `apiKeyId` | [ID](/types/#scalars) | The bound ApiKey identity (optional; validated live in-group at write). Informational v1 — no doom-gate retrofits onto the LIVE ApiKey FSM. |

## Used by

- [createPlugin](/reference/plugin/createPlugin/)
- [deactivatePlugin](/reference/plugin/deactivatePlugin/)
- [doomPlugin](/reference/plugin/doomPlugin/)
- [plugin](/reference/plugin/plugin/)
- [reactivatePlugin](/reference/plugin/reactivatePlugin/)
- [updatePlugin](/reference/plugin/updatePlugin/)