Skip to main content

Connectors

These endpoints need a Keycloak access token. See Authentication. For what each connector type does, see Tools and connectors.

A connector has two parts:

  • config: settings that are not secret, stored in the database and returned by the API
  • credentials: secrets, written to Vault and never returned

List connectors​

GET/connectors

Needs any role on the project. Each entry has id, name, connector_type, config and project_id.

Query parameters​

project_idstringrequired
The project.

Create a connector​

POST/connectors

Writes the credentials to Vault, then creates the connector. If Vault refuses, nothing is created. Needs the developer or admin role on the project.

Body​

idstringrequired
The connector's slug. It is part of every tool ref, so it cannot be changed later.
namestringrequired
Its display name.
connector_typestringrequired
sql, rest_api, mcp, graphql, salesforce, office365 or echo.
project_idstringrequired
The project.
configobjectoptional
Settings for the type. See the table below.
credentialsobjectoptional
Secrets for the type. See the table below.

Responses​

200
Created. Returns the connector without its credentials.
403
You are not a developer or admin on the project.
409
A connector with this id exists.
502
The credentials could not be stored in Vault.

Fields for each type​

Typeconfigcredentials
sqldialect (postgresql, mysql, mssql or oracle), host, port (the dialect's default), database (the SID for Oracle), service_name (Oracle), schema, allowed_tables, max_rows (default 100, at most 1000), timeout_seconds (default 15, at most 60)username, password
mcpurl, transport (streamable_http, the default, or sse), auth, read_only_tools, disabled_toolsDepends on auth
rest_apibase_url, auth, operationsDepends on auth, see below
graphqlendpoint, auth, allow_mutations (default false)Depends on auth, see below
salesforceauth: flow (client_credentials or password) and token_urlclient_id, client_secret, and for the password flow also username, password and optionally security_token
office365auth: tenant_id, and sender_mailbox for sending mailclient_id, client_secret
echoprefixnone

For rest_api and graphql, auth.type is one of:

auth.typeOther auth fieldscredentials
nonenone
api_keyheader (default X-API-Key)api_key
bearertoken
oauth2_client_credentialstoken_urlclient_id, client_secret

rest_api, graphql, mcp, salesforce and office365 connectors can also take user_oauth, to act as each user: {"enabled": true, "provider": "microsoft" | "google" | "salesforce" | "generic", "authorize_url", "token_url", "revoke_url", "scopes", "tenant_id"}, with oauth_client_id and oauth_client_secret in credentials (Salesforce and Microsoft 365 reuse their client_id and client_secret). SQL Server, Oracle and user_oauth need the enterprise_connectors licence feature.

An mcp connector's tools are read from the server, never written by a client. stdio servers, and any command or args, are refused.

Each rest_api operation has name, method, path and optionally description and param_schema. Path parameters go in braces, such as /invoices/{invoice_id}. In param_schema, each parameter has a type (string, number, integer, boolean, array or object), an optional description, and required, which defaults to true.

Remove a connector​

DELETE/connectors/{connector_id}

Deletes the connector's credentials from Vault, then the connector. Agent versions that use its tools keep the tool in their definition, but calls to it fail. Needs the developer or admin role on the project.

Responses​

200
Removed. Returns {"removed": "<connector_id>"}.
404
No such connector.
502
The credentials could not be removed from Vault, so the connector was kept.

More connector routes​

Method and pathWhoWhat it does
PATCH /connectors/{connector_id}developer or adminChange a connector's settings. Credentials stay as they are.
PUT /connectors/{connector_id}/credentialsdeveloper or adminReplace its credentials in Vault.
POST /connectors/{connector_id}/testdeveloper or adminCheck the connection.
POST /connectors/{connector_id}/tools/refreshdeveloper or adminmcp: ask the server for its tools again.
POST /connector-imports/openapideveloper or admin{"project_id", "spec_text"} or {"project_id", "spec_url"}: read an OpenAPI 3 description and return the operations to pick, the authentication it implies and warnings. Stores nothing. A URL is fetched through the connector sandbox, without redirects, up to 5 MB.
GET /connectors/{connector_id}/usageviewerCalls, errors, calls made as a user, and SQL rows, per day.
GET /connectors/{connector_id}/grantsdeveloper or adminThe people connected to a connector that acts as each user.
DELETE /connectors/{connector_id}/grants/{grant_id}developer or adminDisconnect someone. Their token is revoked at the provider and deleted.

Your connections​

For connectors that act as each user. Each person manages their own.

Method and pathWhat it does
GET /me/connectionsThe connectors that act as each user, and whether you have connected yours.
POST /connectors/{connector_id}/oauth/startStart connecting your account. Returns the provider's sign-in address.
POST /connectors/oauth/completeFinish, from the console's callback page.
GET /connectors/{connector_id}/oauth/grants/meYour connection's state.
DELETE /me/connections/{connector_id}Disconnect.
POST /connectors/{connector_id}/oauth/consent-linksWith a project API key: {"external_id": "<your user id>"} returns a consent link for one of your application's users.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →