Patch a connector profile

Updates a connector profile. Secrets resent as __secretvalue:-prefixed placeholders keep their stored values. action_config, event_config and sync_config each replace the stored map when sent as an object: an entry left out is removed, so send every entry that should stay. Omit the field, or send null, to leave it unchanged.

PATCH /v2/connector_profiles/{id}

Patch a connector profile

cURL

curl --request PATCH \
  --url https://api.stackone.com/v2/connector_profiles/{id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "authentication_config_key": "<string>",
  "environment": "<string>",
  "active": true,
  "is_default": true,
  "version": "<string>",
  "pinned_version": "<string>",
  "owner": "<string>",
  "setup_fields": {},
  "secrets": {},
  "action_config": {},
  "event_config": {
    "deel_webhook_employee_created_direct": {
      "enabled": true,
      "webhook_ids": [
        "c4b3f1de-7a2e-4d8b-9f61-5e0a2b7c9d13"
      ]
    },
    "deel_webhook_employee_updated_direct": {
      "enabled": false,
      "webhook_ids": []
    }
  },
  "sync_config": {}
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "connector_key": "<string>",
  "connector": {
    "key": "<string>",
    "name": "<string>",
    "logo_url": "<string>",
    "categories": [
      "<string>"
    ],
    "release_stage": "<string>",
    "authentication_config_label": "<string>"
  },
  "version": {
    "resolved": "<string>",
    "pinned": "<string>",
    "owner": "<string>"
  },
  "accounts_count": 123,
  "enabled_actions_count": 123,
  "active": true,
  "default": true,
  "environment": "<string>",
  "authentication_config_key": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "setup_fields": {},
  "secrets": {},
  "action_config": {},
  "event_config": {
    "deel_webhook_employee_created_direct": {
      "enabled": true,
      "webhook_ids": [
        "c4b3f1de-7a2e-4d8b-9f61-5e0a2b7c9d13"
      ]
    },
    "deel_webhook_employee_updated_direct": {
      "enabled": false,
      "webhook_ids": []
    }
  },
  "sync_config": {}
}

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

id · string · required

The unique identifier of the connector profile.

Query Parameters

expand · string | null

A comma-separated list of additional fields to expand. Supported values: connector (the connector this profile configures), version (the connector version this profile resolves to), accounts_count (the number of accounts linked to this profile) and enabled_actions_count (how many of that version's actions this profile enables). These are returned as null unless requested.

Example:

"connector,version"

Body

application/json

name · string | null

The display name of the connector profile.

authentication_config_key · string | null

The key of the connector's authentication configuration to use. Switching it usually requires resending the setup fields and secrets of the new method.

environment · string | null

The environment of the authentication configuration (e.g. production).

active · boolean | null

Whether the connector profile is active.

is_default · boolean | null

Whether this is the connector's default profile. Marking a profile as default demotes the previous one. false is ignored when the profile ends the request active and no other profile is the default. A disabled profile cannot be made the default: send active: true in the same request, or the request is refused with connector_profile_disabled_cannot_be_default. Resending true to a disabled profile that is already the only default is accepted and changes nothing. Any save that leaves a profile disabled while another profile is also the default clears this flag on it, even when is_default is omitted.

version · string | null

The connector version the profile uses.

pinned_version · string | null

The connector version to pin the profile to. Only applies to Falcon-versioned connectors; ignored otherwise.

owner · string | null

The owner of the pinned connector version (defaults to stackone). Accepts the wildcards builtin (the global stackone owner) and custom (the organization's own connectors).

setup_fields · object | null

The non-secret setup field values, keyed by setup field key. Replaces the saved setup fields when provided.

secrets · object | null

The secret field values, keyed by field key. Replaces the saved secrets when provided: resend a __secretvalue:-prefixed placeholder to keep a stored secret, send an empty object to clear all secrets, or omit the field to leave them unchanged.

action_config · object | null

The per-action enablement of the profile, keyed by action id. Sending it replaces the stored map, so an entry left out is removed. Omit it, or send null, to leave the enabled actions unchanged.

Show child attributes

event_config · object | null

The events the profile processes and the webhooks they are delivered to, keyed by event action id: the id of an entry in event_actions from GET /v2/connectors/{id}?expand=actions (e.g. deel_webhook_employee_created_direct). Each entry sets whether the event action is enabled and, in webhook_ids, which webhooks receive its events. An event action left out is disabled. A webhook id that does not belong to the project fails the request with a 400. Keys are not checked against the connector, so an unknown event action id is stored but never matches an event. Sending it replaces the stored configuration in full, so an event action left out also loses its webhooks. Omit it, or send null, to leave the event configuration unchanged; send {} to disable every event action and remove all its webhook subscriptions.

Show child attributes

Example:

{
  "deel_webhook_employee_created_direct": {
    "enabled": true,
    "webhook_ids": ["c4b3f1de-7a2e-4d8b-9f61-5e0a2b7c9d13"]
  },
  "deel_webhook_employee_updated_direct": { "enabled": false, "webhook_ids": [] }
}

sync_config · object | null

The per-action data-sync configuration, keyed by action id. Sending it replaces the stored map, so an action left out stops syncing. Omit it, or send null, to leave the sync configuration unchanged.

Show child attributes

Response

200

application/json

The connector profile was updated.

id · string · required

The unique identifier of the connector profile.

name · string · required

The display name of the connector profile.

connector_key · string · required

The connector key (e.g. workday). Always present; the full connector object requires ?expand=connector.

connector · object | null · required

The connector this profile configures. Always present; null unless requested via ?expand=connector.

Show child attributes

version · object | null · required

The connector version this profile resolves to. Always present; null unless requested via ?expand=version.

Show child attributes

accounts_count · integer | null · required

The number of accounts linked to this connector profile that are visible to you. Always present; null unless requested via ?expand=accounts_count.

enabled_actions_count · integer | null · required

How many of the connector version's actions this profile enables. For StackOne connectors only the actions in the release stages your organization can access are counted, so this can read lower than the number the profile actually enables; a connector your organization owns is counted in full. A profile that enables everything counts all of them; one naming individual actions counts only those the version still has. 0 when the profile enables nothing, and also whenever no catalogue can be resolved — an unreadable registry, or a connector whose own release stage your organization cannot access. Always present; null unless requested via ?expand=enabled_actions_count on a read endpoint, and always null on create.

active · boolean · required

Whether the connector profile is active.

default · boolean · required

Whether this is the default connector profile.

environment · string | null · required

The environment of the connector profile.

authentication_config_key · string | null · required

The authentication configuration key.

created_at · string<date-time> · required

The timestamp when the connector profile was created.

updated_at · string<date-time> · required

The timestamp when the connector profile was last updated.

setup_fields · object · required

The saved non-secret setup field values, keyed by setup field key.

secrets · object · required

The saved secret fields, keyed by field key. Values are __secretvalue:-prefixed redacted placeholders (never the plaintext); resend a placeholder unchanged to keep the stored secret.

Show child attributes

action_config · object · required

The per-action enablement of the profile, keyed by action id.

Show child attributes

event_config · object · required

The saved event action configuration and the webhooks subscribed to each event action, keyed by event action id. Set it with event_config on create or patch.

Show child attributes

Example:

{
  "deel_webhook_employee_created_direct": {
    "enabled": true,
    "webhook_ids": ["c4b3f1de-7a2e-4d8b-9f61-5e0a2b7c9d13"]
  },
  "deel_webhook_employee_updated_direct": { "enabled": false, "webhook_ids": [] }
}

sync_config · object · required

The per-action data-sync configuration, keyed by action id.

Show child attributes