Connectors & Integrations

Connectors are how Formael interfaces with the external world. Each connector implements capabilities for a specific provider - handling authentication, API calls, response normalization, and error handling so your agents never have to.

The provider model

Your agents never know which provider implements a capability. They target capabilities by name; Formael resolves the correct connector based on your organization's Provider Bindings.

Agent: { "domain": "finance", "action": "create", "entity": "invoice" }
                       ↓
Formael: Provider Binding → finance → Xero
                       ↓
Xero connector executes, returns normalized result

Switching providers is a configuration change. If you migrate from Xero to Stripe, update your Provider Binding - no changes to your agents, policies, or audit trail.

Connector catalog

Finance

ITSM

Contracting

Identity

Sales / CRM

Messaging

Email

File Storage

Calendar

Configuring provider bindings

Provider Bindings connect a capability domain to a specific connector for your organization. Configure them in Settings → Integrations.

Setting up a new integration

1. Navigate to Settings → Integrations → Add Integration
2. Select the provider (e.g., Xero)
3. Authenticate - OAuth2 flows launch directly in the dashboard; API key credentials are entered in a secure form
4. Select which capability domains this provider handles for your organization
5. Save - the binding is immediately active

Formael stores provider credentials encrypted at rest. They are decrypted only at the moment of connector execution and are never logged or returned via any API.

Credential management

Credential rotation is zero-downtime - the new credential is validated before the old one is invalidated.

Connector reliability

Each connector handles provider-specific reliability concerns:

Rate limiting. Connectors track per-provider rate limits and surface 429 responses as failed_retryable outcomes with backoff guidance.

Error normalization. Provider-specific error codes are mapped to Formael's normalized error taxonomy. Your agents receive a consistent error structure regardless of which provider responded.

Response normalization. Provider responses are translated to the capability's defined return schema. Your agent always receives the same structure for finance.create.invoice, regardless of whether Xero or Stripe executed it.

Org Connector Overrides

When your organization adds custom fields to a capability's parameter schema - for example, an internalReferenceId field on finance.create.invoice - the connector's default parameter mapping doesn't know about them. Org Connector Overrides let you patch a connector's behavior for your organization without building a custom integration.

An override is configured per capability and applied automatically at execution time.

What overrides can do

What overrides cannot do

Overrides are intentionally shallow. They are not programmable. The following require a full custom integration instead:

• Changing the connector's authentication method
• Replacing the provider's base URL
• Adding conditional logic or multi-step flows

Configuring an override

Navigate to Settings → Integrations → [Provider] → Overrides and select the capability you want to customize. The override editor lets you define your parameter mappings and test them before saving.

Testing an override before it goes live

Use the dry-run endpoint to preview how an override would transform a sample intent without affecting live execution:

POST /manage/v1/connectors/{connectorId}/overrides/{domain}/{action}/{entity}/test

Pass a sample intent body and the response shows exactly how the override would modify the outbound request and extract the response.

Requesting new connectors

Don't see the integration you need? Contact us to request a connector. Connectors added to the catalog are available to all Formael organizations.