Skip to main content
POST/extensions-admin/{slug}/enable

Enable Extension

Enables a registered extension on the specified project.

It does these steps:

  • binds the manifest's declared permission grants
  • provisions a per-project SQL schema (k9o_<proj_id>_ext_<slug>)
  • applies schema migrations
  • issues a per-project plugin token
  • deploys any declared background functions
  • fires the install (first enable) or activate (re-enable) lifecycle hook

Returns 201 Created on first enable and 200 OK on re-enable from a disabled state.

The response includes the hookSecret (HMAC shared secret for X-K9o-Hook-Signature verification) which is delivered exactly once per enable cycle.

Returns K9O_EXTENSION_REAUTHORISATION_REQUIRED (409) if the manifest version adds permissions since the prior enable; call POST .../reauthorise first.

Requires PROJECT_ADMIN.

Parameters
slug *path
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
reviewedVersionstring

Needed only for an extension that asks to invoke any function (*): the registry version you reviewed.

If the registry has moved on, the enable is refused with 409 K9O_EXTENSION_WILDCARD_REVIEW_STALE.

Ignored otherwise.

aadBindingsobject[]

For an extension with an Azure Event Grid webhook path: the audience and issuer each path's tokens are checked against.

Each entry needs all three strings, otherwise 400 K9O_INVALID_FIELD_VALUE.

path *string

The declared webhook ingress path this binding applies to.

expectedAudience *string

The audience the Azure Event Grid token must carry.

expectedIssuer *string

The issuer the Azure Event Grid token must come from.

Responses
HTTPK9O CodeDescription
200Success
201Created
400K9O_EXTENSION_MANIFEST_INVALIDThe extension manifest fails schema validation at enable time; the field that failed is identified in the error context.
400K9O_EXTENSION_SLUG_INVALIDThe extension slug does not match the required format and cannot be resolved.
400K9O_EXTENSION_CUSTOM_TOKEN_SLUG_MISMATCHA `custom_tokens` key in the manifest does not start with `--ext-<the manifest's own slug>-`; `context.field` names the key.
401K9O_SESSION_EXPIREDYour session has expired; authenticate again to continue.
403K9O_ACCESS_DENIEDYour role does not permit enabling extensions on this project; a PROJECT_ADMIN role is required.
403K9O_EXTENSION_PERMISSION_DENIEDThe extension's manifest-declared permissions do not authorise this operation on the project. Or the manifest grants (audit, read, project) and the registering org is not first-party (reason audit_project_scope_first_party_only).
403K9O_RBAC_DENYThe manifest grants the project-wide audit read and the caller is below PROJECT_ADMIN (reason audit_project_scope_requires_project_admin).
404K9O_EXTENSION_NOT_FOUNDNo extension with this slug exists in the registry.
409K9O_EXTENSION_REAUTHORISATION_REQUIREDThe extension's manifest has been updated with additional permissions since the last enable; re-authorise to proceed.
409K9O_EXTENSION_UNREGISTEREDThe extension has been unregistered from the org and is in its grace period; new enables are no longer permitted.
Response body (200)
data *object
installId *string

The project's install record for the extension (xinst_...).

extensionSlug *string

The extension's slug.

projectId *string

The project's id (proj_...).

manifestVersion *string

The version now enabled, major.minor.patch.

status *"enabled"

Always enabled.

extensionSchema *string

The name of the database schema that holds the extension's own tables on this project.

functions *object

The functions the manifest declares.

inserted *integer

Functions registered for the first time.

reactivated *integer

Functions registered earlier and switched back on.

mcpTools *object

The MCP tools the manifest declares.

inserted *integer

Tools registered for the first time.

reactivated *integer

Tools registered earlier and switched back on.

iframe *any
One of: object
published *boolean

True when every console file was written.

False when any file failed; the install itself still succeeded.

route *any
One of: "managed" | "byos"
or: null
keyPrefix *any
One of: string
or: null
iframeEntryPath *any
One of: string
or: null
errorCode *any
One of: string
or: null
successCount *integer

How many files were written.

failureCount *integer

How many files failed to write.

or: null
warningsstring[]

Present only when something succeeded with a caveat. iframe_not_published:<code> means the install worked but its console files were not published.

hookSecret *string

The secret that signs the platform's calls to the extension's lifecycle hooks (base64url).

It is shown only on this response and is new each time the extension is enabled; store it now.

webhookSecrets *object[]

The signing secret created for each inbound webhook path that needs one.

Empty when none were created now.

path *string

The declared webhook ingress path.

secret *string

The signing secret the sender must use for this path.

Shown only here; no later read returns it.

webhookVerifyTokens *object[]

For each Meta webhook path, the verify token, shown once.

Empty when none were created now.

path *string

The declared webhook ingress path.

verifyToken *string

The token to enter in Meta's dashboard when it verifies the endpoint.

Shown only here.

meta *any
Response body (201)
data *object
installId *string

The project's install record for the extension (xinst_...).

extensionSlug *string

The extension's slug.

projectId *string

The project's id (proj_...).

manifestVersion *string

The version now enabled, major.minor.patch.

status *"enabled"

Always enabled.

extensionSchema *string

The name of the database schema that holds the extension's own tables on this project.

functions *object

The functions the manifest declares.

inserted *integer

Functions registered for the first time.

reactivated *integer

Functions registered earlier and switched back on.

mcpTools *object

The MCP tools the manifest declares.

inserted *integer

Tools registered for the first time.

reactivated *integer

Tools registered earlier and switched back on.

iframe *any
One of: object
published *boolean

True when every console file was written.

False when any file failed; the install itself still succeeded.

route *any
One of: "managed" | "byos"
or: null
keyPrefix *any
One of: string
or: null
iframeEntryPath *any
One of: string
or: null
errorCode *any
One of: string
or: null
successCount *integer

How many files were written.

failureCount *integer

How many files failed to write.

or: null
warningsstring[]

Present only when something succeeded with a caveat. iframe_not_published:<code> means the install worked but its console files were not published.

hookSecret *string

The secret that signs the platform's calls to the extension's lifecycle hooks (base64url).

It is shown only on this response and is new each time the extension is enabled; store it now.

webhookSecrets *object[]

The signing secret created for each inbound webhook path that needs one.

Empty when none were created now.

path *string

The declared webhook ingress path.

secret *string

The signing secret the sender must use for this path.

Shown only here; no later read returns it.

webhookVerifyTokens *object[]

For each Meta webhook path, the verify token, shown once.

Empty when none were created now.

path *string

The declared webhook ingress path.

verifyToken *string

The token to enter in Meta's dashboard when it verifies the endpoint.

Shown only here.

meta *any
cURL
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/extensions-admin/demoext/enable' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Showing example in cURL

Request example
{
  "reviewedVersion": "string",
  "aadBindings": [
    {
      "path": "string",
      "expectedAudience": "string",
      "expectedIssuer": "string"
    }
  ]
}
Response example (200)
{
  "data": {
    "installId": "string",
    "extensionSlug": "string",
    "projectId": "string",
    "manifestVersion": "string",
    "status": "enabled",
    "extensionSchema": "string",
    "functions": {
      "inserted": 0,
      "reactivated": 0
    },
    "mcpTools": {
      "inserted": 0,
      "reactivated": 0
    },
    "iframe": {
      "published": false,
      "route": "managed",
      "keyPrefix": "string",
      "iframeEntryPath": "string",
      "errorCode": "string",
      "successCount": 0,
      "failureCount": 0
    },
    "warnings": [
      "string"
    ],
    "hookSecret": "string",
    "webhookSecrets": [
      {
        "path": "string",
        "secret": "string"
      }
    ],
    "webhookVerifyTokens": [
      {
        "path": "string",
        "verifyToken": "string"
      }
    ]
  }
}
Response example (201)
{
  "data": {
    "installId": "string",
    "extensionSlug": "string",
    "projectId": "string",
    "manifestVersion": "string",
    "status": "enabled",
    "extensionSchema": "string",
    "functions": {
      "inserted": 0,
      "reactivated": 0
    },
    "mcpTools": {
      "inserted": 0,
      "reactivated": 0
    },
    "iframe": {
      "published": false,
      "route": "managed",
      "keyPrefix": "string",
      "iframeEntryPath": "string",
      "errorCode": "string",
      "successCount": 0,
      "failureCount": 0
    },
    "warnings": [
      "string"
    ],
    "hookSecret": "string",
    "webhookSecrets": [
      {
        "path": "string",
        "secret": "string"
      }
    ],
    "webhookVerifyTokens": [
      {
        "path": "string",
        "verifyToken": "string"
      }
    ]
  }
}

More in Extensions