Connector studio

The Connector studio screen lets you write a Connector manifest, check it live and on the server against the connector-manifest contract, save it as a new version and test the connection through the egress guard. Portal path: /studio/connectors. It is used by developers and tenant administrators who connect agents to a business system.

What the screen shows

• On the left, the list of the connectors (GET /v1/connectors), paginated, with New on top. An empty list shows No connector yet: credentials are references (openbao:// or env://), never values.
• Editor tab: Manifest (JSON) checked live against the connector-manifest JSON Schema (schemas read with GET /v1/contracts/{name}), the editor problems, Invalid JSON: ... when the text does not parse, the buttons Validate on the server and Create or Save as a new version, the validation result and the answer of the save.
• Test tab, once a saved connector is open: Connection test with the Test the connection button and its JSON answer.
• The starter manifest new-connector describes a REST system with base_url, an oauth2 authentication whose credential_ref is an OpenBao reference, scopes and one records resource in read.
• Opening a connector reads its stored manifest with GET /v1/manifests/{kind}/{name} (kind Connector).

Actions

Button or action	What it does	API call	Roles
New	Loads the starter manifest new-connector.	None	Everyone
Click a connector in the list	Loads its stored manifest.	GET /v1/manifests/{kind}/{name}	Every signed in user
Validate on the server	Validates the manifest against connector-manifest.	POST /v1/contracts/{name}/validate	Every signed in user
Create	Applies the new manifest.	POST /v1/manifests/apply	tenant_admin, developer
Save as a new version	Applies the manifest with the patch number of metadata.version raised by one.	POST /v1/manifests/apply	tenant_admin, developer
Test the connection (tab Test)	Calls the system through the egress guard with the stored credentials.	POST /v1/connectors/{name}/test	tenant_admin, developer, application_owner
Retry (error state)	Reads the list or the schemas again.	GET /v1/connectors or GET /v1/contracts/{name}	Every signed in user

Roles

The portal enables the save buttons for STUDIO_WRITERS (tenant_admin, developer). POST /v1/manifests/apply requires the same roles. POST /v1/connectors/{name}/test requires tenant_admin, developer or application_owner (WRITE_ROLES, services/control-plane/src/eai/domains/connectors/routes.py).

Typical tasks

Create a connector

1. Start from the template. Click New. Expected result: the manifest new-connector. If it fails: reload the page.
2. Describe the system. Set metadata.name, spec.base_url, spec.auth and spec.resources. Put the secret in OpenBao and write only its reference in credential_ref. Expected result: No problem found by the editor. If it fails: fix the line named by the problem.
3. Validate on the server. Click Validate on the server. Expected result: Valid against contracts/v1. If it fails: read the error list.
4. Create. Click Create. Expected result: the toast Saved as version 0.1.0. If it fails: see Troubleshooting.

Test the connection

1. Open the connector. Click it in the list. Expected result: the Test tab appears. If it fails: save the connector first.
2. Test. Open Test and click Test the connection. Expected result: the JSON answer of the test. If it fails: check the credential reference and the egress policy.

warning

Never paste a password or a token in the manifest. The manifest is stored and versioned: use an openbao:// or env:// reference.

Troubleshooting

Symptom	Cause	Fix
Error invalid_manifest (422)	The manifest breaks the contract.	Fix the fields listed in errors.
Error connector_not_found (404) on test	The connector is not stored.	Create it first.
Error connector_disabled (409)	The connector is disabled.	Enable it on the Connectors page.
Error credential_unavailable (409)	The credential reference cannot be read.	Check the secret behind credential_ref.
Error upstream_error (502)	The business system answered with an error.	Check base_url and the system itself.
Error forbidden (403)	A required role is missing.	Ask for the developer role.

Related pages

• Connector development
• Connectors (capabilities)
• Secrets
• Contracts