Integration Contract

The registry fails fast on an invalid manifest

const manifest = {
  key: 'acme-tickets',
  version: '1.0.0',
  provider: { name: 'tickets.acme.example' },
  displayName: 'Acme Tickets',
  description: 'Import events and fulfill ticket purchases.',
  capabilities: [
    'account', 'groups', 'events', 'ticket_inventory',
    'ticket_fulfillment', 'manual_sync', 'scheduled_sync',
  ],
  fulfillment: { retrySafety: 'manual_reconciliation' },
  auth: {
    methods: [{
      key: 'token',
      label: 'Access token',
      flow: 'token',
      fields: [{
        name: 'token', label: 'Access token', type: 'token', required: true,
      }],
    }],
  },
  catalog: { authType: 'token', enabledByDefault: false },
  actions: { refresh: true, configure: false, disconnect: true },
};

Capabilities declare dependencies; actions declare controls

Optional actions control the operator interface. Refresh must befalse unless manual_sync is declared. Configure must befalse unless a real configure() hook exists. Disconnect can expose the common owner-scoped operation and an optional provider revocation hook. A missing action means unavailable behavior, not a placeholder button.

• Use actions.refresh: true only for the common manual-sync path.
• Use actions.configure: true only when configuration can be validated and applied through the adapter hook.
• Use actions.disconnect: true to expose credential clearing and imported-resource deactivation; upstream revocation runs only when the adapter implements its optional disconnect hook, and historical records remain retained.
• Use sync.resourceConcurrency for bounded persistence tuning; the platform clamps it to 10.

Choose one of four authentication flows

Auth method keys use snake_case. Supported field types are email,password, tel, text, token, andurl, with optional required, minimum-length, pattern, and safe validation message metadata. Authentication hooks also receive the resolved Provider record so they can read protected application configuration.

1. 1

   Start securely

   Validate the method and fields, then let the platform sign short-lived opaque auth state bound to the provider, method, owner, acting user, team account, fields, and upstream challenge.

2. 2

   Echo state unchanged

   The client returns the opaque auth_state. It cannot replace the original subject or fields during completion.

3. 3

   Return a credential envelope

   Return a required access token and optional expiry and refresh token, plus an optional canonical account and safe metadata.

4. 4

   Refresh only when declared

   A credential-refresh adapter returns the same envelope shape from refreshCredential and distinguishes invalid credentials from transient provider failures.

Errors are typed, safe, and operationally useful

• Use a stable code, a safe public message, an appropriate status, and retryable only when repetition is safe.
• Never attach passwords, tokens, codes, cookies, authorization headers, full provider responses, signed URLs, or private buyer data to errors or raw logs.
• Treat every auth field, challenge, provider payload, webhook, and payment field as untrusted input.
• Scope all work to the platform-supplied user and resolved Provider; never trust ownership IDs returned by the provider or sent by a client.
• Apply application and edge/shared-store throttling to password, token, and verification-code attempts.
• Confirm the provider permits every official and private/organizer workflow before shipping it.

All clients use the common integration service