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.

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.

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.

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.

Runtime selection

CIP / capabilities / integration tests     →  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 quick reference

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, sync bridge against syncExecution, and capability readiness on datasources.

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.
• Authentication UI shows one card per authentications[] item; manifest/Builder API defines slots — operators assign secrets per usage after upload.

Related reading

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