Skip to main content
POST
Create a connector profile

Authorizations

Authorization
string
header
required

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

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 callback_url (the OAuth callback URL the provider app must allow for this profile). These are returned as null unless requested.

Example:

"connector,version"

Body

application/json
connector_key
string
required

The key of the connector to configure (e.g. workday).

authentication_config_key
string
required

The key of the connector's authentication configuration to use.

environment
string
required

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

name
string
required

The display name of the connector profile.

active
boolean | null
default:false

Whether the connector profile is active.

is_default
boolean | null

Whether this is the connector's default profile. When omitted, the first ACTIVE profile created for a connector becomes the default (a profile created disabled leaves the slot empty until one is enabled). An explicit true requires active to be true, otherwise the request is refused with connector_profile_disabled_cannot_be_default. When it replaces an existing default it requires permission to update that profile, and the previous default is demoted.

version
string | null

The connector version the profile is created for.

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.

secrets
object | null

The secret field values, keyed by field key. Stored encrypted.

action_config
object | null

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

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.

Example:
sync_config
object | null

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

sync_event_subscriptions
object | null

The webhooks notified of the record changes each sync finds, keyed by the action id of a sync in sync_config. Each action must have a sync, enabled or not, and each webhook must belong to the project; otherwise the request is refused with sync_event_subscriptions_invalid or sync_event_subscription_webhook_not_found. A webhook may appear once per action. On create, each action must be in sync_config in the same request.

Example:
callback_domain
string | null

The hostname of one of the organization's active custom domains (e.g. auth.example.com) that the OAuth callback is served on, in place of StackOne's API host. null or omitted uses StackOne's default. Setting one requires custom domains to be enabled for the organization, otherwise the request is refused with callback_domain_not_enabled_for_organization. It also requires a project or organization admin, otherwise the request is refused with callback_domain_admin_required. A hostname that is not an active custom domain of the organization is refused with callback_domain_not_available.

Example:

"auth.example.com"

Response

The connector profile was created.

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.

version
object | null
required

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

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.

callback_domain
string | null
required

The hostname of the organization's custom domain the OAuth callback is served on. null when the profile uses StackOne's default.

Example:

"auth.example.com"

callback_url
string | null
required

The OAuth or OIDC callback URL to allow in the provider app for this profile. With a callback_domain it is always https://<callback_domain>/connect/oauth2/<connector_key>/callback. Without one it is the redirectUri set in the setup fields or declared by the connector, otherwise the standard callback path on StackOne's API host. null when the authentication configuration is neither OAuth 2.0 nor OIDC. Always present; null unless requested via ?expand=callback_url.

Example:

"https://auth.example.com/connect/oauth2/hubspot/callback"

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.

action_config
object
required

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

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.

Example:
sync_config
object
required

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

sync_event_subscriptions
object
required

The webhooks notified of the record changes each sync finds, keyed by action id. Set it with sync_event_subscriptions on create or patch.

Example: