Configure Connected System authentication

Connected Systems need trusted credentials before sync, webhooks, CIP, or AI-assisted capabilities can run. Authentication is declared on the Connected System manifest as authentications[] — one or more credential slots, each with a usage that tells the platform when to apply it.

Secrets resolve at deploy/upload time via kv:// references only — never hardcoded in docs or committed JSON.

Why it matters

Operational Trust requires enterprise-approved auth patterns (API key, OAuth2, client credentials) — not bypass security. Wrong or conflated auth blocks upload, integration tests, webhook validation, sync-bridge propagation, and every certification pillar that touches live APIs.

Separate usages exist on purpose: user-scoped api credentials must not power background sync workers or inbound webhook signature checks. Enterprise Synchronization Fabrix depends on webhookInbound and syncExecution slots in addition to api.

Authentication layers

Do not confuse vendor slots with platform login — a green aifabrix auth status does not fix vendor 401 errors. See Platform developer access.

The authentications[] model

Each Connected System declares an array of authentication entries. Every item reuses the same credential structure (authType, credential.method, variables, security kv paths) and adds:

Usage values (Connected System)

There is no webhook-specific auth schema — each slot uses the same credential / apiProvider shapes as today.

Single authentication (API only)

A single root authentication block on the Connected System covers normal api usage. Validate compiles it as the default API slot when multi-usage arrays are present in your toolchain.

When you add webhooks or sync bridge, extend with additional credential entries using the same shape and explicit usage values — do not duplicate secrets in datasource JSON.

Prerequisites

• <systemKey>-system.json from aifabrix create or copied fixture
• Builder secret store paths in env.template for each slot’s security keys
• Authentication methods catalog
• Build with Builder MCP for post-upload Authentication UI
• When enabling webhooks or sync bridge: Enterprise sync bridge — technical guide

Where it lives

Builder MCP

Use help topic connectedSystemUi for post-upload Authentication URL and required secret keys per usage. Normative loop: Build with Builder MCP.

How to set

1. Default API slot

Detect vendor reality — OpenAPI import often classifies CRM specs as OAuth2; private apps often need API key.

aifabrix repair <systemKey> --auth apikey
aifabrix validate <systemKey>

repair --auth updates the default api credential block (or the default slot in authentications[] when present).

2. Add webhook and sync slots (when needed)

When a Business Entity enables webhook.enabled or syncBridge other than disabled, the Connected System must expose matching auth usages:

On-behalf-of user OAuth alone is invalid for syncExecution — use service account, client credentials, or API key suited to background workers.

3. Example — three usage slots

{
  "key": "example-crm",
  "displayName": "Example CRM",
  "type": "openapi",
  "authentications": [
    {
      "key": "default",
      "usage": "api",
      "authType": "credential",
      "credential": {
        "method": "apikey",
        "variables": {
          "baseUrl": "https://api.example.com",
          "headerName": "X-API-Key"
        },
        "security": {
          "apiKey": "kv://example-crm/apiKey"
        }
      }
    },
    {
      "key": "webhook",
      "usage": "webhookInbound",
      "authType": "credential",
      "credential": {
        "method": "apikey",
        "variables": {
          "headerName": "X-Hub-Signature"
        },
        "security": {
          "apiKey": "kv://example-crm/webhookSecret"
        }
      }
    },
    {
      "key": "sync-worker",
      "usage": "syncExecution",
      "authType": "credential",
      "credential": {
        "method": "apikey",
        "variables": {
          "baseUrl": "https://api.example.com",
          "headerName": "X-API-Key"
        },
        "security": {
          "apiKey": "kv://example-crm/syncApiKey"
        }
      }
    }
  ]
}

syncExecution may reuse the same kv path as api when one service credential is appropriate — keep separate slots so validation and audit stay explicit.

4. Resolve secrets and prove auth

aifabrix auth status
aifabrix login
aifabrix validate <systemKey>
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

Confirm every kv:// path in env.template exists (secret get … --exists). After upload, operators assign live secrets on Connected Systems → Authentication — one form per usage card.

Upload pushes credential references only. If denied, fix platform permissions and re-upload rather than embedding secrets in JSON.

Auth types and on-behalf-of

Runtime selection (summary)

CIP / capabilities / integration tests     →  authentications[usage=api]
POST /webhooks/{systemKey}/…               →  authentications[usage=webhookInbound]
Sync job / SyncIntent / syncBridge write   →  authentications[usage=syncExecution]

Detail: Enterprise webhooks, Configure sync.

Defaults and examples

Validate

aifabrix validate <systemKey>
aifabrix verify-trust <systemKey>
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

Certification checks webhook shape against webhookInbound, sync bridge against syncExecution, and get/update capabilities on the datasource — see Enterprise sync bridge — technical guide.

Auth failures surface earliest at integration or E2E. Rotate credentials in the secret store; re-upload after rotation if connection settings change.

Common mistakes

Limits

Do not grant Role Assistants or models direct credential access — capabilities mediate execution. Vendor-specific OAuth scopes, webhook signature schemes, and certificate rotation vary — confirm against vendor docs and Authentication methods catalog.

Datasource manifests still require root key, displayName, systemKey, entityType, resourceType, primaryKey, and indexed externalId — system auth does not replace those bands. validate alone can stay green while live calls fail if secrets are stale — re-run test-integration after every rotation.

Related reading

• Enterprise sync bridge — technical guide
• Enterprise webhooks
• Configure sync
• Operational trust — authentication