configure-connector

• ForbiddenError (403): you are not an admin.
• PolicyDenied (403): a policy would have held the call for approval.
• ValidationError (400): the platform refused the values, with its reason.
• NotFound (404): the platform found nothing to configure.
• ConflictError (409): the change collides with the platform's current state.

• connector_id: the connector this call created, or the one it changed. Pass it to the other connector tools.
• status: the connector's status, as the platform gives it. When the platform gives none: awaiting_authentication when it asks for a further step, otherwise ready.
• auth_url: present only when the provider signs the person in, the https:// page to open next.

An example response, for a new ServiceNow connector whose provider does not sign the person in.

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000014\",\"result\":{\"connector_id\":\"6b1a3d5e7f9c0b2a4d6e8f01\",\"status\":\"ready\"}}"
    }
  ],
  "isError": false
}

{
  "lifecycle_id": "qlc_000014",
  "result": {
    "connector_id": "6b1a3d5e7f9c0b2a4d6e8f01",
    "status": "ready"
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  "connector_id": "6b1a3d5e7f9c0b2a4d6e8f01",
  "status": "ready"
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000014'

# a dict subclass; `result` is already unwrapped
{
 "connector_id": "6b1a3d5e7f9c0b2a4d6e8f01",
 "status": "ready"
}

out.lifecycle_id  # 'qlc_000014' — an attribute, not a key

For a provider that signs the person in, the answer also carries auth_url, the page to open to finish connecting.

The PolicyDenied message names the policy's reason and says to configure the connector in the console instead. Every password, key and token in om_connection is masked like credentials. Changing a connector with connector_id sends only what you pass, so it keeps its triggers, tags and schedule. A data source's connection cannot be changed with connector_id: delete the connector and provision it again. The error codes are S8:connector-admin-only (not an admin), S5:policy (a policy would have held it) and S4:validate-input (the arguments). Dotted om_connection ids such as authType.password may be passed as they are or nested. Credential values the platform's refusal quotes are masked. The platform's own reason is the message on NotFound, ConflictError and the 400 ValidationError.

The field ids under credentials in the example are illustrative: take the real ones from get-connector-form for your category. A value in angle brackets is one only you can supply, and the platform refuses a literal <...>.

To provision one, pass the category, a name and credentials. Wexa starts from the category's template, fills in your values and saves the connector. The platform validates the values and keeps the secrets in its vault. Some providers sign the person in after the connector is saved. For those, the answer carries auth_url: open it to finish.

To connect a data source such as Snowflake, pass om_connection instead of credentials. Wexa sends the same body the console's Data Sources wizard does, with no template read first. A connector that needs no credentials is connected with provision-connector instead, and a WhatsApp account with connect-whatsapp.

The credentials are never logged, stored or returned. The call is never held for approval, because an approval request would store its arguments: a policy that would hold it refuses it instead, with PolicyDenied, and writes nothing to the approvals store. The credentials argument is masked wherever Wexa records the call's arguments. When the platform's refusal quotes a value you sent, Wexa replaces the value with ••• before the error reaches you. The answer carries only connector_id, status and auth_url, never the saved configuration. Do not log the credentials in your own code either.

Every call that tries to save the connector writes a configure-connector.run audit event, with the category, the connector, the access scope, the ids of the fields that were set, and the outcome: configured or failed. It records which fields were set, never their values. A failed call records the error, with any credential value in it masked. A call refused before the save, for example by the admin check, writes no such event.

Not marked consequential, for the same reason it is never held: an approval would store the credentials. So the project's write gate does not apply to it. What protects it instead is that only an admin may call it, as in the console.

See also list-connector-catalog, delete-connector and list-connectors.