Authentication methods catalog

Configure page: Configure authentication. This catalog is the usage + method matrix and JSON examples for Connected System credentials.

Authentication has two dimensions integrators must combine:

1. usage — which runtime path loads the credential (api, webhookInbound, syncExecution, …)
2. credential.method — how the vendor validates the call (API key, OAuth2, bearer token, certificate, …)

Both live on authentications[] in <systemKey>-system.json. Platform developer login (aifabrix login) is a separate layer — see Platform developer access.

Prerequisites

• <systemKey>-system.json from aifabrix create or copied fixture
• env.template with kv:// paths for every slot’s security keys
• Business Entity features that need extra usages: Enterprise webhooks, Enterprise sync bridge

Where it lives

Each authentications[] item:

There is no separate webhook or sync auth schema — every slot uses the same credential shapes.

AI Fabrix-facing APIs authenticate callers with OAuth2 authorization code under governed real-user authority. That inbound contract is separate from how the Connected System reaches a vendor downstream.

How to set

1. Create or refresh the Connected System — start from aifabrix create <app> --type external or an existing fixture; avoid leading with wizard-only flows when repairing auth.
2. Align the default API slot — when OpenAPI import assumed OAuth but you use a private app or API key:

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

3. Add usage slots — append authentications[] entries for each runtime path you enable (webhookInbound, syncExecution, messageInbound, …). Copy the credential shape from the api slot; change only key, usage, and security kv paths.
4. Wire env.template — one kv:// reference per secret key; never commit values.
5. Upload and test — operators complete secrets on Connected Systems → Authentication; integrators run test-integration and E2E to prove each slot.

repair --auth updates the default api credential block only — add additional slots manually when webhooks, sync, or channels require separate usages.

Usage catalog

Feature → required usage

On-behalf-of user OAuth is valid for api only — not for syncExecution or webhookInbound.

Credential method catalog

Applies inside any usage slot when authType: credential.

System vs none: choose system for platform shells and facades where AI Fabrix obtains the target token through the Controller. Choose none only when the vendor truly accepts unauthenticated calls. There is no bearerForward auth type.

Wizard OpenAPI import often defaults CRM specs to oauth2. Private apps frequently need:

aifabrix repair <systemKey> --auth apikey

repair --auth updates the default api credential block.

Platform-managed system authentication (no vendor secrets on the slot)

{
  "key": "example-platform-facade",
  "displayName": "Example platform facade",
  "description": "Illustrative platform facade using system authentication",
  "type": "openapi",
  "authentication": {
    "authType": "system"
  },
  "authentications": [
    {
      "key": "default",
      "usage": "api",
      "authType": "system"
    }
  ]
}

Use system when AI Fabrix owns downstream token acquisition. Do not add credential or apiProvider on that slot. Callers of AI Fabrix-facing APIs still authenticate as governed users (OAuth2 authorization code) — system is not an autonomous actor identity. Prefer authentications[]; keep root authentication aligned when your toolchain still requires it.

Multi-slot examples

API key — three usages (CRM + webhooks + sync)

{
  "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 reference the same kv path as api when one service credential is appropriate — keep separate slots for validation and audit.

OAuth2 client credentials — api + syncExecution

{
  "authentications": [
    {
      "key": "default",
      "usage": "api",
      "authType": "credential",
      "credential": {
        "method": "oauth2",
        "variables": {
          "baseUrl": "https://graph.microsoft.com/v1.0",
          "tokenUrl": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
          "grantType": "client_credentials",
          "scope": "https://graph.microsoft.com/.default"
        },
        "security": {
          "clientId": "kv://example-sp/clientId",
          "clientSecret": "kv://example-sp/clientSecret",
          "tenantId": "kv://example-sp/tenantId"
        }
      }
    },
    {
      "key": "sync-worker",
      "usage": "syncExecution",
      "authType": "credential",
      "credential": {
        "method": "oauth2",
        "variables": {
          "baseUrl": "https://graph.microsoft.com/v1.0",
          "tokenUrl": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
          "grantType": "client_credentials",
          "scope": "https://graph.microsoft.com/.default"
        },
        "security": {
          "clientId": "kv://example-sp/clientId",
          "clientSecret": "kv://example-sp/clientSecret",
          "tenantId": "kv://example-sp/tenantId"
        }
      }
    }
  ]
}

Single authentication (extend when needed)

One root authentication object is enough for api-only integrations. Add authentications[] entries with usage: webhookInbound or usage: syncExecution when you enable those features — same credential shape as the API block.

Communication channel — split api and webhookInbound

Used when systemKind: communication. Prefill header and algorithm names in webhookInbound variables; keep the outbound bot token on api. Operators supply secrets after upload.

{
  "key": "example-messaging",
  "displayName": "Example Messaging Channel",
  "type": "custom",
  "systemKind": "communication",
  "authentications": [
    {
      "key": "default",
      "usage": "api",
      "authType": "credential",
      "credential": {
        "method": "bearerToken",
        "security": {
          "apiKey": "kv://example-messaging/botToken"
        }
      }
    },
    {
      "key": "webhook",
      "usage": "webhookInbound",
      "authType": "credential",
      "credential": {
        "method": "hmac",
        "writeOnce": true,
        "variables": {
          "algorithm": "sha256",
          "signatureHeader": "X-Example-Signature",
          "timestampHeader": "X-Example-Timestamp",
          "signaturePrefix": "v0=",
          "timestampMaxAge": "300"
        },
        "security": {
          "signingSecret": "kv://example-messaging/signingSecret"
        }
      }
    }
  ]
}

Use oidc on webhookInbound when the vendor validates inbound requests with OpenID Connect instead of HMAC. Complete pending secrets on Connected Systems → Authentication before channel probe. See Deliver assistant channels and Configure webhook change signals.

Runtime selection

CIP / capabilities / outbound bot calls    →  authentications[usage=api]
POST /webhooks/…                           →  authentications[usage=webhookInbound]
Sync job / SyncIntent / syncBridge         →  authentications[usage=syncExecution]
OAuth redirect / callback                  →  authentications[usage=callback]

Builder CLI (platform) auth

Independent of vendor authentications[]:

aifabrix login
aifabrix auth status

CI/CD: aifabrix login --method credentials --app <appKey> with secrets in secrets.local.yaml.

Defaults and examples

Minimal single-slot default (extend with authentications[] when features require more usages):

{
  "authentication": {
    "authType": "credential",
    "credential": {
      "method": "apikey",
      "variables": { "baseUrl": "https://api.example.com", "headerName": "X-API-Key" },
      "security": { "apiKey": "kv://example-system/apiKey" }
    }
  }
}

Multi-slot JSON examples appear in the sections above (CRM + webhooks + sync, OAuth client credentials, communication api + webhookInbound). Use those fragments as templates — swap kv:// paths and vendor URLs for your Connected System.

Validate

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

401/403 on integration test → fix the usage slot that path uses (api vs syncExecution), not governance subjects.

Certification checks webhook config against webhookInbound. Change-signal events still require CIP get. Capability-named events[] require the named operation instead — do not add a fake get. Sync bridge still requires syncExecution and datasource get/update.

Limits

Vendor OAuth scopes, webhook signature schemes, certificate rotation, and delegated user flows vary — confirm against vendor documentation. This catalog does not enumerate every schema variant the external-system validator accepts.

• Datasource identity (key, resourceType, indexed externalId, …) is independent of auth — see entity configure guides.
• validate checks shape; live TLS, token refresh, and webhook signature proof require test-integration or E2E.
• Confirm capability-named webhook dispatch is live on your deployment before pointing vendor Request URLs at /webhooks/….
• Authentication UI shows one card per authentications[] item; manifest/Builder API defines slots — operators assign secrets per usage after upload.

Related reading

• Configure authentication
• Configure webhook change signals
• Enterprise sync bridge — technical guide
• Enterprise webhooks
• Platform developer access