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. Keep outbound vendor tokens on api and inbound signing/OIDC on webhookInbound. 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
• Edit Connected Systems with Builder API 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. Safe edit loop: Edit Connected Systems with Builder API.

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. Communication channel credentials (systemKind: communication)

Assistant delivery uses Connected Systems with systemKind: communication. They share the Authentication tab with vendor integrations — same UI surface, one card per usage.

Split inbound Request URL validation from outbound bot calls. Prefill non-secret header/algorithm/OIDC discovery fields in each slot’s credential.variables. Declare secrets as kv:// in credential.security only. Upload creates pending credentials; operators complete them in the UI.

Do not put the inbound signing secret on the api slot. Vendor Request URLs POST to /webhooks/{systemKey}/{datasourceKey} and authenticate with webhookInbound — the same door used for CRM change signals. Event names that match a capability key run that operation; see Configure webhook change signals.

Probe and delivery steps: Deliver assistant channels. Per-channel: Slack, Teams, Copilot, ChatGPT, Claude.

5. 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 / outbound bot calls    →  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. Change-signal events[] still require CIP get (and idPath). When every events[] entry is a capability key on that entity, get / idPath are not required — prove the named operation instead. Sync bridge still requires syncExecution and get/update — 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.

Capability-named webhook events use the same webhookInbound slot and generated POST /webhooks/… URL as change signals. Confirm with your operator that capability dispatch is live before registering vendor Request URLs. Change-signal events still need CIP get; capability-only events[] do not.

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

• Configure webhook change signals
• Enterprise sync bridge — technical guide
• Enterprise webhooks
• Configure sync
• Deliver assistant channels
• Operational trust — authentication