# Connect your website to Aiomize using your own AI

Paste the instructions from your Aiomize customer portal into Codex, Claude or another coding AI with access to your project. Your AI installs the website-side connection using your permissions. Aiomize staff do not need your server login.

This guide describes the public connection contract. Aiomize's optimization engine, algorithms and system instructions remain private.

## Choose the connection your platform permits

Your AI should detect the actual framework, runtime, hosting plan and publication process. Prefer an existing supported connection. Use current official platform documentation; do not invent hooks, endpoints or permissions.

| Platform | Website-side approach |
| --- | --- |
| Node.js, Next.js, Nuxt, Astro, SvelteKit, Express | Server-rendering integration; use the static client if the deployed output is static. |
| Static HTML, Hugo, Jekyll, exported sites | Explicit URL-to-file mapping, private durable snapshots, publication lock and verified file publication. |
| WordPress, WooCommerce | Site-owned plugin, supported hooks or authorized publishing APIs; preserve existing SEO plugins. |
| Shopify | Permitted app/backend and theme app extension or authorized publishing API. |
| Drupal, Joomla, Ghost, Magento, PrestaShop | Supported extension, rendering or publishing APIs for the installed version. |
| PHP, Python, .NET, Java, custom CMS | A thin server-side connection using the signed-payload contract below. |
| Webflow, Wix, Squarespace, BigCommerce and other hosted platforms | Inspect the actual plan and authorized publishing/export/backend capabilities. Some changes may be unavailable. |
| Cloudflare or another edge runtime | A customer-owned, narrowly scoped response transformation; secrets remain in the edge secret manager. |
| Git and build/CI deployment | Existing publication workflow, protected secrets, durable backups and live verification. A PR alone is not publication. |

For example, [WordPress documents the wp_head hook](https://developer.wordpress.org/reference/hooks/wp_head/), [Shopify documents theme app extensions](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration), and [Cloudflare documents HTMLRewriter](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/). These are platform capabilities, not a claim that every site or hosting plan permits every change. Do not expose a connection key in a theme, Liquid, browser script or public asset.

Full automation requires a permitted server-side, build-time, publishing-API or edge path. If the host does not offer one, report the specific limitations. Do not silently migrate hosting or DNS. A browser-only script is not a substitute for server-side SEO.

Automated connector publication requires HTTPS on the registered website. For an HTTP-only site, establish a permitted HTTPS configuration before attempting connector publication; do not migrate hosting or DNS without the customer's approval.

## Ownership and credentials

1. Register the website in your customer portal. Your copied instructions include the public ownership proof if verification is still needed.
2. Add that proof through your own website/DNS access and verify ownership in the portal.
3. For a static website, choose Static HTML / generated website in the installation platform selector before creating the connector key. Then create a connector key in the portal. Keep it in protected server-side configuration or your hosting secret manager. The copied AI instructions never include the key. Do not paste the key into AI chat.
4. Use `AIOMIZE_SITE_ID` and `AIOMIZE_CONNECTOR_KEY` from the portal. A reporting API key is read-only and is not a connector key.

Installation instructions are available across platform categories. End-to-end support is verified per deployed website. Our own static website flow has been publicly verified; a newly installed external adapter still requires its own verification.

## Published website-side clients

- [Node.js connector](https://aiomize.ai/assets/aiomize-connector.cjs): `createAiomizeMiddleware({siteId, key})` and `verifyManifest`/`applyHtml`. Mount the middleware before HTML rendering/static routes. It preserves the original renderer. It does not persist changed templates or itself submit a publication receipt.
- [Static publication client](https://aiomize.ai/assets/aiomize-static-connector.cjs): `createPublisher({stateDir, request})` and the exported fixed-endpoint `request`. Keep `aiomize-connector.cjs` beside it. Run `publisher.run({siteId, key, origin, root, routes})` in your existing deployment context. Node.js 22 or later is the supported runtime.
- [Signed-payload verifier for Node.js](https://aiomize.ai/assets/aiomize-integration-client.cjs): `verifyEnvelope(envelope, {siteId, key})`; keep `aiomize-connector.cjs` beside it.

For the static client, `stateDir` must be a private durable directory outside the public website. `root` must be the real absolute website directory. `origin` is the exact website origin. `routes` explicitly maps public paths to explicit relative HTML filenames (including generated subdirectories without symbolic links) and the permitted `robots.txt`/`llms.txt` filenames. Never derive filesystem paths directly from arbitrary URLs. Every runner and other writer of those website files must use the same publication lock. Preserve ownership and permissions. Adapt the invocation to your own hosting environment; do not request Aiomize's infrastructure configuration.

## Retrieve approved changes

Send an authenticated server-to-server request:

```http
GET https://aiomize.ai/portal-api/connector/manifest?site=YOUR_SITE_ID&format=signed_payload
Authorization: Bearer YOUR_CONNECTOR_KEY
```

`YOUR_SITE_ID` and `YOUR_CONNECTOR_KEY` denote your protected configuration, not literal credentials or values to paste into the AI prompt. Do not follow redirects or send this authorization header to another host. Use bounded timeouts and response sizes. A five-minute poll is sufficient; polling does not trigger or authorize extra scans.

The response has `version: 1`, `algorithm: "hmac-sha256"`, `encoding: "utf-8"`, a `payload` string and a lowercase hexadecimal `signature`. The payload ceiling is 2 MiB; allow at most 4 MiB plus 4 KiB for the JSON envelope.

Verify HMAC-SHA256 over the **exact UTF-8 bytes of the decoded payload string** using the **64-character connector key as a UTF-8 string**. Do not hex-decode the key or reserialize the payload before verification. Use a standard cryptographic library and constant-time comparison. Then parse the authenticated JSON.

The payload contains `siteId`, `website`, `batchId`, `status`, `generatedAt`, `fixes`, and `fixesDigest`. Check the exact configured site ID and origin. Reject timestamps older than one hour or more than one minute in the future. `fixesDigest` is the signed SHA-256 digest to submit in a publication receipt; other languages do not need to reproduce JavaScript JSON serialization. A missing batch or an empty fixes array means there is nothing to apply.

The default request without `format=signed_payload` remains available for the published Node/static clients and returns the original manifest object with its signature.

## Validate and apply

Each fix contains `id`, `fixId`, `target`, `content`, and `summary`. The server supplies current approved changes subject to the website's active plan and selected pages. Before applying, enforce no more than 50 fixes, bounded content, unique fix IDs and exact same-origin targets without credentials, fragments or query strings. Map only explicitly permitted publication routes.

- `file`: only `/robots.txt` and `/llms.txt`; maximum content size 65,536 characters. Write as text, never execute it.
- `meta`: `target.url` identifies the page; `target.field` is `title` or `description`. HTML-escape content and preserve the existing rendering structure. Maximum 300 characters.
- `head-jsonld`: `target.url` identifies the page. Parse JSON, preserve existing facts and `@graph` structures, avoid duplicates, and escape `<` when emitting JSON inside an HTML script element. Do not insert executable HTML. Ambiguous existing entities require review.
- `onion-location`: requires a separately supported response-header integration. Do not publish it through a static HTML or unsupported adapter. Saved private onion details do not by themselves authorize public advertising or prove Tor transport.

Apply supported complete validated changes under the automatic optimization mandate enabled in Aiomize. Respect any separate approval requirement and the current pause state; do not require a new manual approval for every routine update. Do not apply a restored batch again automatically. Saved changes require private durable backup and crash recovery; response overlays must retain the original renderer and fail safely to the original response. If authorization, signature validation or delivery fails, make no new changes.

## Verify publication

Downloading a manifest, installing a module or creating a PR does not prove that live changes are present. Verify the public URL and CDN/cache behavior after publication. Stored changes must be restored if verification fails. Local restoration must remain possible even if the connection is unavailable; report failed remote acknowledgement separately.

For publications that can provide exact stable byte evidence, submit:

```http
POST https://aiomize.ai/portal-api/connector/receipt?site=YOUR_SITE_ID
Authorization: Bearer YOUR_CONNECTOR_KEY
Content-Type: application/json
```

The JSON request contains:

- `action`: `verify` or `rollback`.
- `batchId`: the authenticated batch ID.
- `digest`: the authenticated `fixesDigest`.
- `files`: one entry per public target, at most 50. Each entry has its exact public `url`, lowercase SHA-256 `beforeHash` and `afterHash`, Boolean `beforeExists`, and the unique fix `id` values in `fixIds`. Use the empty-byte hash if the original file did not exist. Cover every current approved fix exactly once.

The request ceiling is 64 KiB. The response includes `verified`, `status` and per-URL `checks`. Only `verified: true` with the expected `status` confirms the public check. The service rechecks public bytes and current authorization itself. It accepts only stable evidence matching the approved changes, not a caller's success claim. If the batch or approval changed, do not force an old receipt through.

Dynamic pages with changing nonces, timestamps or personalized output may not provide this stable evidence. Do not disable security controls or falsely mark them verified. Prefer an appropriate stable publication path or report which additional verification capability is needed.

Unauthorized or paused delivery returns 401/403; changed approval or batch returns 409; exhausted installation allowance returns 429. Do not retry state-changing operations blindly. Reconcile local saved state and current approved changes first.

## Acceptance checks

Before enabling automation, verify correct-site publication, rejection of forged/expired/wrong-site payloads, duplicate execution, blocked paths, timeouts, partial failures, backup recovery and public output. Confirm that no secrets reach HTML, JavaScript bundles, public files or logs. Keep the existing plan limits and schedule. Finish by reporting installed capabilities, tested public URLs, how to disable/restore the integration and remaining platform restrictions.


## Complete the customer setup

In the customer portal, open Websites & business and use **Copy instructions to your AI**
or download the instructions for the selected website. Give the instruction to your
own agent; store connector credentials separately in protected hosting settings.

The instruction covers platform inspection, ownership, installation, publication
verification and rollback. Then use Connections to authorize the correct Search
Console and Analytics accounts/properties. The owner completes Google sign-in and
consent. Confirm existing tags before installing anything; use the customer's own
measurement ID and avoid duplicates. Google reporting access and tag installation
are separate tasks. Enter the business facts, market and languages once and keep
them current. Check actual status and reports; a saved link is not an API connection.

## Activate persistent technical updates

A newly created static publisher key starts paused. It can authenticate and receive a signed empty manifest so the portal can confirm contact. After installation, complete your business profile and use **Activate technical updates** in the website card. Review the scope and check the permission box once. The existing plan scan schedule and publication allowance apply; activation does not buy extra scans.

The permission covers supported rule-based metadata, structured data, llms.txt and sitemap references through the static publisher. Bot-access policy and onion publication require separate permission. AI-written content, design experiments and advertising are separate capabilities. Pausing this permission stops new updates and leaves the static files in place. A changed business profile requires review before proposals based on it can be published. Existing Node response overlays remain a separate connection path; they do not persist source templates and are not marked as the persistent Growth Engine capability.