Integrations Ownership, Migration, and Rollback

Ownership boundaries

This monorepo owns:

• the /integrations/v1 runtime in workers/consumer-api
• the canonical integrations contract in packages/api-contract
• installation, credential, origin verification, and audit control-plane flows in apps/dashboard
• integrations documentation in apps/docs
• contract, runtime, and resilience checks under tests/

This monorepo does not own:

• WordPress plugin implementation
• Drupal module implementation
• consumer SDK implementations

Those consumers should live in separate repositories and integrate against the published API contract and documentation from this repo.

Coordination contract for external consumers

External consumer repositories should treat these artifacts as canonical:

• OpenAPI source: packages/api-contract/src/integrations.openapi.ts
• generated docs: /reference/integrations-api
• runtime base path: /integrations/v1
• auth header: X-API-Key
• contract validation lanes: pnpm test:integrations:contract, pnpm test:integrations:runtime, pnpm test:integrations:resilience

If an external consumer needs a new capability, update the contract and runtime here first, then update downstream consumer repositories.

Rollout guidance

1. Add or change the integrations contract in packages/api-contract.
2. Implement matching runtime behavior in workers/consumer-api and dashboard control-plane flows if needed.
3. Regenerate docs and update migration notes in this repo.
4. Run the integrations contract/runtime/resilience suites.
5. Only after the API surface is stable should external consumer repositories update their implementations.

Reference runbook: /docs/runbooks/integrations-api-rollout.md

This keeps the API contract authoritative and prevents individual consumer repositories from drifting into undocumented behavior.

Migration guidance for existing consumers

Consumers still using legacy public API key flows should migrate to installation-scoped credentials:

1. Create an installation in the dashboard.
2. Register one or more origins for that installation.
3. Complete origin verification.
4. Issue an installation credential and scope it to the minimum required read capabilities.
5. Update the external consumer repository to call /integrations/v1 with X-API-Key.
6. Verify the new flow with the contract and runtime checks before removing legacy credentials.

Recommended migration posture:

• run old and new consumers in parallel for a short validation window when possible
• migrate one installation at a time
• keep credentials scoped narrowly during rollout
• monitor dashboard audit history for scope denials, origin mismatches, and invalid credential events

Rollback guidance

If an integrations rollout causes consumer regressions:

1. stop promoting new consumer releases that depend on the changed behavior
2. restore the prior API behavior if the regression is in this repo and backward compatibility was unintentionally broken
3. if the API behavior is correct but the consumer is not, roll back the external consumer repository release
4. keep or reissue the prior installation credential if needed during rollback
5. confirm health, installation resolution, and the affected scoped endpoint behavior before resuming rollout

Rollback must preserve the published contract or clearly version any intentional breaking change before consumers upgrade.

Pull request expectations in this repo

When changing the integrations surface in this monorepo:

• update packages/api-contract first or in the same change
• regenerate docs artifacts from the canonical contract
• run the integrations contract/runtime/resilience validation lanes
• document any downstream action required in external consumer repositories
• avoid merging undocumented runtime behavior that external consumers could discover accidentally

Repository split expectations

Consumer repositories should avoid embedding undocumented assumptions about:

• dashboard-only routes
• internal D1 schema details
• Better Auth tables or metadata layouts
• non-versioned public API behavior outside /integrations/v1

This monorepo remains the source of truth for integrations API behavior; consumer repositories remain replaceable clients.

WordPress recipe: list all people

This section is for WordPress (or any other integrations consumer) that needs to list people using an installation credential.

Endpoint and auth:

• Method: GET
• URL: https://api.legaciti.org/integrations/v1/people
• Header: X-API-Key: <installation-credential>
• Required scope: people.read

Optional query parameters:

• page (default 1, minimum 1)
• per_page (default 20, minimum 1, maximum 100)
• q (optional free-text filter on name/ORCID)

Example request:

curl -sS "https://api.legaciti.org/integrations/v1/people?page=1&per_page=100&q=" \
  -H "X-API-Key: $INTEGRATION_API_KEY" \
  -H "Accept: application/json"

Expected 200 response shape:

{
  "people": [
    {
      "orcid_id": "0000-0002-1825-0097",
      "name": "Ada Lovelace",
      "biography": null,
      "last_fetched_at": 1762050000000,
      "sync_status": "complete",
      "publication_count": 12
    },
    {
      "orcid_id": "0000-0001-2345-6789",
      "name": {
        "en": "Joao Silva",
        "pt": "Joao Silva"
      },
      "biography": {
        "en": "Researcher in marine ecology",
        "pt": "Investigador em ecologia marinha"
      },
      "last_fetched_at": 1762040000000,
      "sync_status": "complete",
      "publication_count": 7
    }
  ],
  "page": 1,
  "per_page": 100,
  "total": 2,
  "pages": 1,
  "q": ""
}

Common error responses to handle:

• 400 invalid query parameters
• 401 missing or invalid credential
• 403 inactive credential, unverified origin, or missing scope
• 429 installation rate limit exceeded