Skip to main content

Connectors

The Connectors screen lets you list the connections to business systems, store their credentials in the Credential Broker (they are never returned), test a connector, start and follow its synchronizations, change its owner or status, and delete it. Portal path: /capabilities/connectors. Developers and application owners register and test connectors; tenant administrators and security officers handle the credentials. The screen is drawn by portal/src/screens/capabilities.tsx.

What the screen shows​

  • Connectors table, read with GET /v1/connectors (every connector in one call, by name). Columns: Name, System, Auth type, Credentials (the stored credentials with their kind, metadata and update date, never their values), Status, Updated. Empty: No connector, hint Apply a Connector manifest below.
  • A click on a row, or View details, opens a side panel with GET /v1/connectors/{name}.
  • Apply a manifest panel prefilled with a Connector manifest sample (portal/src/samples/connector-manifest.json), with Reset example and Apply.

Actions​

Button or actionWhat it doesAPI callRoles
Refresh (icon)Reloads the list.GET /v1/connectorsAny tenant member
Row click or View detailsOpens the connector record.GET /v1/connectors/{name}Any tenant member
Row menu CredentialsForm Kind (required: api_key, oauth2_client, basic, webhook_secret, service_account) and the write only fields API key, Client id, Client secret, Username, Password, Secret, Token. Empty fields are not sent; the values go to the Credential Broker.POST /v1/connectors/{name}/credentialstenant_admin, security_officer
Row menu TestTests the connection with the stored credential and shows the result.POST /v1/connectors/{name}/testtenant_admin, developer, application_owner
Row menu SyncStarts a synchronization (answer 202) and shows the answer.POST /v1/connectors/{name}/synctenant_admin, developer, agent
Row menu Sync runsShows the last synchronizations of the connector.GET /v1/connectors/{name}/sync-runsAny tenant member
Row menu EditForm Owner and Status (active, disabled).PATCH /v1/connectors/{name}tenant_admin, developer, application_owner
Row menu DeleteOpens Confirm a destructive action; type the connector name, then Confirm.GET /v1/lineage/graph, then DELETE /v1/connectors/{name}tenant_admin
Reset example / ApplyRestores the sample / applies the Connector manifest.POST /v1/manifests/applytenant_admin, developer
Retry (error state)Sends the failed read again.Same callSame roles
danger

The credential fields are write only: the portal never reads them back and the API never returns them. Type them on a trusted workstation and never paste a secret in Apply a manifest: a manifest refers to a secret, it does not hold it.

Roles​

The portal hides no button. In services/control-plane/src/eai/domains/connectors/routes.py: credentials need tenant_admin or security_officer; test and edit need WRITE_ROLES (tenant_admin, developer, application_owner); sync needs OPS_ROLES (tenant_admin, developer, agent); delete needs tenant_admin; reading needs a tenant. platform_admin passes every role check.

Typical tasks​

Connect a business system​

  1. Apply the manifest. The manifest describes the system, the authentication and the allowed scopes. In Apply a manifest, paste your Connector manifest, then click Apply. Expected result: Manifest applied and the connector in the table after Refresh. If it fails: fix the errors listed under the editor.
  2. Store the credential. The Credential Broker keeps it and lends it to the runtime. In the row menu, click Credentials, choose the Kind, fill only the matching fields, then click Credentials. Expected result: the toast Done and the kind in the Credentials column. If it fails: forbidden means you are neither tenant_admin nor security_officer.
  3. Test the connection. The test asks the Credential Broker for the authentication headers and, when the manifest has a base_url, calls it. Click Test. Expected result: a side panel with ok: true and credentials: ok (plus http_status). If it fails: ok: false comes with an error, for example egress_denied (the address is refused by the egress policy) or upstream_unavailable; a missing or refused credential shows as credential_unavailable or credential_rejected.

Synchronize a connector and follow it​

  1. Start the synchronization. Only one synchronization runs at a time. Click Sync. Expected result: a side panel with the accepted synchronization. If it fails: sync_in_progress means another one is running; sync_disabled means the manifest disables synchronization.
  2. Follow it. Each synchronization is recorded. Click Sync runs. Expected result: the list of the last synchronizations with their status. If it fails: click Refresh and try again.

Disable a connector​

  1. Edit its status. A disabled connector refuses synchronizations, credential leases and webhooks. Click Edit, choose disabled in Status, then click Edit. Expected result: the status Disabled. If it fails: forbidden means you lack tenant_admin, developer or application_owner.

Troubleshooting​

SymptomCauseFix
connector_not_found (404)The name is wrong or the connector was deleted.Copy the name from the table.
connector_disabled (409): "The connector is disabled."The status is disabled.Set it back to active with Edit.
credential_rejected (502): "The identity provider rejected the credential."The secret is wrong or expired.Store a new credential with Credentials.
credential_unavailable (502): "The credential is not available."No credential of the expected kind is stored, or its reference cannot be read.Store it with Credentials.
sync_in_progress (409): "A synchronization is already in progress."A synchronization is running.Wait for its end in Sync runs.
sync_disabled (409)The manifest disables synchronization.Enable it in the manifest and apply it again.
scope_not_allowed (403)A requested scope is not allowed for this connector.Use only the scopes of the manifest.
Test shows error: egress_deniedThe egress policy refuses the address of base_url.Ask the security team to allow the host.