Connector Token Rotation

Connector tokens (ss_connector_*) are the only credential a CMS module needs. They authorize writes to AACsearch and survive across module restarts. This page explains the full lifecycle and the rotation procedure every operator should run on a schedule.

Token model recap

• Prefix: ss_connector_
• Scope: connector_write (writes via Connector API only — no read access, no admin)
• Stored as: SHA-256 hash (prefix:hash) in SearchApiKey.hash
• Plaintext returned once at creation, never again
• Bound to: one organization (tenant) and one search index
• Reusable across: any number of CMS instances pointing at the same index

The plaintext value is shown one time in the dashboard. There is no API to fetch the plaintext later. If a token is lost, the only path is rotation.

Creating a token

1. Dashboard → Connectors → New Connector Token.
2. Pick the search index the token writes to.
3. (Optional) Add a label describing where the token will be used — for example, prestashop-staging, bitrix-prod, shopify-eu.
4. Click Create. Copy the plaintext token immediately and store it in your secrets manager.

The token is created in the active state and is usable for writes the moment it appears.

Rotation procedure

Rotate tokens at least every 90 days and on every personnel change in the team that holds the secret. The procedure is create → swap → revoke, never the other order — never revoke first, or the connector goes blind until the swap lands.

Step-by-step

1. Create a new token with the same index binding as the old one. Label it with the rotation date (bitrix-prod-2025-04).
2. Roll out the new token to every CMS instance pointing at the same index:
   • PrestaShop: paste into the module settings page, save, click Test connection.
   • Bitrix: update the module setting via admin UI or PHP config file; reload.
   • WordPress: update the AACsearch → Settings field; trigger a wp aacsearch diagnose to verify.
   • Shopify-style server connector: update the AACSEARCH_CONNECTOR_TOKEN env var; restart the service.
   • Strapi: update plugin config in admin or config/plugins.{js,ts}; restart Strapi.
3. Verify that the new token is in use:
   • From the dashboard, watch the new token's lastUsedAt timestamp move forward.
   • The old token's lastUsedAt should freeze.
   • In Connectors → Sync history, recent jobs should show the new token's label.
4. Wait at least 24 hours with both tokens active. This catches any CMS instance you forgot to update (cron jobs, secondary servers, background workers).
5. Revoke the old token from Dashboard → Connectors → [token] → Revoke. Revocation is immediate.
6. Confirm that no requests arrive from the old token (its lastUsedAt stays frozen after revocation). If a hidden client surfaces, the next call returns 403 invalid_or_revoked_key and the operator can re-issue or trace it.

Why both tokens at once

Multiple ss_connector_* tokens can coexist for the same index. They are independent rows in SearchApiKey. This is the foundation of zero-downtime rotation: the old token keeps working while the new one is rolled out.

Revoking a token

Use revoke when:

• Rotation is complete and the old token is no longer in use.
• A token has leaked (in a screenshot, accidentally committed to git, sent over an insecure channel).
• A CMS instance is decommissioned.

Revocation is immediate and irreversible. There is no "undo." The next call from a revoked token returns:

{ "error": "invalid_or_revoked_key" }

with HTTP 403. Existing in-flight requests fail; queued retries on the CMS side will hit the same 403 until the operator re-issues a new token and rolls it out.

Leak response

If you suspect a token has leaked, the response sequence is:

1. Revoke immediately from the dashboard. Don't wait — the cost of a temporary outage is lower than the cost of writes from an attacker.
2. Issue a new token for the same index. Roll it out to every CMS instance using the procedure above.
3. Audit the index for unexpected writes:
   • Dashboard → Connectors → Sync history — filter by date range and look for unfamiliar batches.
   • Check the index for documents with external_id patterns you don't recognize.
4. Audit downstream — if the same token was reused for other indices (it should not be — one token per index), revoke and re-issue those too.
5. Rotate the channel the leak came from: change the password on the shared doc, force-rotate the CI secret, etc.

The Connector API has no read access — a leaked connector token cannot exfiltrate documents, customer data, or analytics. It can only write garbage into the bound index. Revocation closes that quickly.

Scope hygiene

The connector_write scope is the only scope a CMS module needs. The dashboard's UI only generates connector tokens with that scope, and the API rejects any wider scope on token creation.

Do not reuse a connector token as a search token. They serve different surfaces:

Mixing them defeats both halves of the security model: a search token in the CMS would lose write access; a connector token in the browser would expose write credentials to every visitor.

Per-environment tokens

Use one token per environment:

• bitrix-staging — your staging Bitrix instance
• bitrix-prod — your production Bitrix instance
• bitrix-disaster-recovery — the standby instance, if you have one

When an environment is decommissioned, revoke its token before tearing down the infrastructure. Tokens that outlive their CMS instance are the most common cause of "ghost writes" in audits.

Programmatic rotation

For operators who want to script the rotation cycle:

• POST /api/v1/keys — create a new connector token (admin auth required, connector_write scope).
• DELETE /api/v1/keys/:id — revoke a token by ID.
• GET /api/v1/keys?prefix=ss_connector_ — list active connector tokens.

See v1 REST API for the full reference. The same oRPC procedures (search.createConnectorToken, search.revokeApiKey) drive the dashboard, so any rotation that runs on a schedule should call the v1 endpoints rather than scraping the admin UI.

Related pages

• Connectors Overview
• Connector API Lifecycle
• Diagnostics — including how revoked tokens surface as errors
• Custom Connector