Custom actions — how an org composes its own

🚧 Design

How orgs extend the Action Library with their own actions. Same model as managed; the org defines it and runs the operation.

Built exactly like a managed action

A custom action uses the same grammar, the same variable kinds, the same ceiling, and the same lifecycle as a managed one. Only two things differ: the org defines it (not Axowl), and the operation runs in the org’s own system.

To compose one, an org supplies four things:

Part	What it is	Example (a logistics org)
Target entity	a business object — an existing Axowl entity, or one the org names	Shipment
Action verb	what is done to it	approve
Variable slots	the limits the grant can carry, each with a kind	region[set] · value[num]
Event	a custom event the action emits (sealed into the chain)	shipment.approved

That composes the catalog entry:

shipment.approve:region=KR,value<=50000,uses=*
└─ scope ─┘ └────── variable bag ──────┘

The operation lives in the org's system

For a managed action, Axowl runs the operation (e.g. ActivateBinding). For a custom action, the operation usually runs in the org’s own system — Axowl screens the grant (pre-grant gate), seals the decision, and emits the event; the org’s app performs the actual work and reports back over the SDK. Axowl is the authority and the seal, not the executor.

Composition rules

• Same grammar. namespace.resource.action:key{op}value — the org picks the namespace (their system) and resource (their entity).
• Same kinds. Ceiling-bearing [ref] entity-reference · [set] categorical · [num] numeric (compared by subsume), and [in] input-only (carried, not compared) — the operator encodes the kind, the value is always a string.
• Same ceiling. A custom action is still bounded by the approver’s authority — an org admin can only delegate within what they hold.
• Same lifecycle. uses / ttl / exp apply unchanged (ttl / exp are the time add-on).
• Same RiskLevel model. The org assigns a RiskLevel → it routes to the matching approval tier, exactly like managed actions.
• Origin = custom. Stored as an org-scoped catalog row (IsSystemPermission = false), versus managed rows on the system org.

Defining a custom action is itself a high-risk action

Adding an entry to the catalog is registerCustomEvent / defineCustomAction — a platform-tier action. “The right to define rights” is governed at the top RiskLevel, not handed out with everyday grants.

Managed vs custom — at a glance

	Managed	Custom
Defined by	Axowl (code + event catalog)	the org (in-app)
Operation runs in	Axowl	the org’s own system (via SDK)
Catalog row	system org · IsSystemPermission	org-scoped row
Removable	no (Axowl-owned)	yes (the org’s own)
Grammar · kinds · ceiling · lifecycle	—	identical

---

Related: Action Library · Event & system control · Capability grants · SDK overview