# Enable Extension

`POST /extensions-admin/{slug}/enable` · Core · Extensions

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

| Name | In | Required | Description |
|---|---|---|---|
| `slug` | path | yes |  Example: `"demoext"`. |
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `reviewedVersion` | string | no | 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. |
| `aadBindings` | array of object | no | 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`. |
| `aadBindings.[]path` | string | yes | The declared webhook ingress path this binding applies to. |
| `aadBindings.[]expectedAudience` | string | yes | The audience the Azure Event Grid token must carry. |
| `aadBindings.[]expectedIssuer` | string | yes | The issuer the Azure Event Grid token must come from. |

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.installId` | string | yes | The project's install record for the extension (`xinst_...`). |
| `data.extensionSlug` | string | yes | The extension's slug. |
| `data.projectId` | string | yes | The project's id (`proj_...`). |
| `data.manifestVersion` | string | yes | The version now enabled, `major.minor.patch`. |
| `data.status` | enum ("enabled") | yes | Always `enabled`. |
| `data.extensionSchema` | string | yes | The name of the database schema that holds the extension's own tables on this project. |
| `data.functions` | object | yes | The functions the manifest declares. |
| `data.functions.inserted` | integer | yes | Functions registered for the first time. |
| `data.functions.reactivated` | integer | yes | Functions registered earlier and switched back on. |
| `data.mcpTools` | object | yes | The MCP tools the manifest declares. |
| `data.mcpTools.inserted` | integer | yes | Tools registered for the first time. |
| `data.mcpTools.reactivated` | integer | yes | Tools registered earlier and switched back on. |
| `data.iframe` | object | yes |  |
| _one of_ | | |  |
| `data.iframe.published` | boolean | yes | True when every console file was written. False when any file failed; the install itself still succeeded. |
| `data.iframe.route` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.keyPrefix` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.iframeEntryPath` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.errorCode` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.successCount` | integer | yes | How many files were written. |
| `data.iframe.failureCount` | integer | yes | How many files failed to write. |
| _or_ | | |  |
| `data.warnings` | array of string | no | Present only when something succeeded with a caveat. `iframe_not_published:<code>` means the install worked but its console files were not published. |
| `data.hookSecret` | string | yes | 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. |
| `data.webhookSecrets` | array of object | yes | The signing secret created for each inbound webhook path that needs one. Empty when none were created now. |
| `data.webhookSecrets.[]path` | string | yes | The declared webhook ingress path. |
| `data.webhookSecrets.[]secret` | string | yes | The signing secret the sender must use for this path. Shown only here; no later read returns it. |
| `data.webhookVerifyTokens` | array of object | yes | For each Meta webhook path, the verify token, shown once. Empty when none were created now. |
| `data.webhookVerifyTokens.[]path` | string | yes | The declared webhook ingress path. |
| `data.webhookVerifyTokens.[]verifyToken` | string | yes | The token to enter in Meta's dashboard when it verifies the endpoint. Shown only here. |
| `meta` | object | yes |  |

- **201**: Created

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.installId` | string | yes | The project's install record for the extension (`xinst_...`). |
| `data.extensionSlug` | string | yes | The extension's slug. |
| `data.projectId` | string | yes | The project's id (`proj_...`). |
| `data.manifestVersion` | string | yes | The version now enabled, `major.minor.patch`. |
| `data.status` | enum ("enabled") | yes | Always `enabled`. |
| `data.extensionSchema` | string | yes | The name of the database schema that holds the extension's own tables on this project. |
| `data.functions` | object | yes | The functions the manifest declares. |
| `data.functions.inserted` | integer | yes | Functions registered for the first time. |
| `data.functions.reactivated` | integer | yes | Functions registered earlier and switched back on. |
| `data.mcpTools` | object | yes | The MCP tools the manifest declares. |
| `data.mcpTools.inserted` | integer | yes | Tools registered for the first time. |
| `data.mcpTools.reactivated` | integer | yes | Tools registered earlier and switched back on. |
| `data.iframe` | object | yes |  |
| _one of_ | | |  |
| `data.iframe.published` | boolean | yes | True when every console file was written. False when any file failed; the install itself still succeeded. |
| `data.iframe.route` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.keyPrefix` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.iframeEntryPath` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.errorCode` | object | yes |  |
| _one of_ | | |  |
| _or_ | | |  |
| `data.iframe.successCount` | integer | yes | How many files were written. |
| `data.iframe.failureCount` | integer | yes | How many files failed to write. |
| _or_ | | |  |
| `data.warnings` | array of string | no | Present only when something succeeded with a caveat. `iframe_not_published:<code>` means the install worked but its console files were not published. |
| `data.hookSecret` | string | yes | 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. |
| `data.webhookSecrets` | array of object | yes | The signing secret created for each inbound webhook path that needs one. Empty when none were created now. |
| `data.webhookSecrets.[]path` | string | yes | The declared webhook ingress path. |
| `data.webhookSecrets.[]secret` | string | yes | The signing secret the sender must use for this path. Shown only here; no later read returns it. |
| `data.webhookVerifyTokens` | array of object | yes | For each Meta webhook path, the verify token, shown once. Empty when none were created now. |
| `data.webhookVerifyTokens.[]path` | string | yes | The declared webhook ingress path. |
| `data.webhookVerifyTokens.[]verifyToken` | string | yes | The token to enter in Meta's dashboard when it verifies the endpoint. Shown only here. |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_EXTENSION_MANIFEST_INVALID` | The extension manifest fails schema validation at enable time; the field that failed is identified in the error context. |
| 400 | `K9O_EXTENSION_SLUG_INVALID` | The extension slug does not match the required format and cannot be resolved. |
| 400 | `K9O_EXTENSION_CUSTOM_TOKEN_SLUG_MISMATCH` | A `custom_tokens` key in the manifest does not start with `--ext-<the manifest's own slug>-`; `context.field` names the key. |
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired; authenticate again to continue. |
| 403 | `K9O_ACCESS_DENIED` | Your role does not permit enabling extensions on this project; a PROJECT_ADMIN role is required. |
| 403 | `K9O_EXTENSION_PERMISSION_DENIED` | The 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). |
| 404 | `K9O_EXTENSION_NOT_FOUND` | No extension with this slug exists in the registry. |
| 409 | `K9O_EXTENSION_REAUTHORISATION_REQUIRED` | The extension's manifest has been updated with additional permissions since the last enable; re-authorise to proceed. |
| 409 | `K9O_EXTENSION_UNREGISTERED` | The extension has been unregistered from the org and is in its grace period; new enables are no longer permitted. |
| 403 | `K9O_RBAC_DENY` | The manifest grants the project-wide audit read and the caller is below PROJECT_ADMIN (reason audit_project_scope_requires_project_admin). |

## Code samples

### cURL

```bash
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 '{}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/extensions-admin/demoext/enable', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/enable-extension
