Individual tools: 500 tools loaded · ~150,000 tokens

Advanced Tool Search: 2 tools · ~900 tokens

Illustrative, exact counts depend on the actions enabled and the model. ## Example flows | Linked connector | User prompt | Search tool finds | Execute tool runs | |------------------|-------------|-------------------|--------------------| | *Any* | A description of the task | Ranked actions with IDs and descriptions: only from the connectors you've linked | The chosen `action_id` with its params | | HiBob | "Request time off for Alice next Friday" | `hibob_create_time_off_request` | Creates the time-off request in HiBob | | Jira | "Look up ticket ABC-123" | `jira_get_issue` | Returns the issue details from Jira | | Google Drive | "Find training docs on GDPR" | `googledrive_list_files` | Searches the linked drive for matching files | ## Setting it for a whole project **Project Settings → General → MCP Settings** decides this for every new connection in a project, rather than leaving it to whoever authorizes: | Setting | Effect | |---|---| | **Allowed** | On by default. Turn it off and connections can only use individual tools, and Advanced Tool Search is refused even if a client requests it | | **Mode: Let the connecting user choose** | The default. The consent screen shows a **Load tools when needed** toggle, on unless the user turns it off | | **Mode: Enforced for all connections** | Always used, and the consent screen shows the decision instead of a toggle | The setting applies to new connections, so it does not change grants that already exist. Where a mode is not enforced here, each user chooses it on the consent screen while authorizing, with a toggle labelled **Load tools when needed**. See [AI Platforms](/connect/ai-platforms/overview#what-the-user-sees) for where it appears. ## When to use it Use Advanced Tool Search when your agent spans many SaaS systems — dozens to thousands of tools — or targets models with limited context windows. For a small, focused action set where you want the model to see every tool, use individual tools instead. Turn it on in an AI platform, with ready-to-paste configs for ChatGPT, Claude, Cursor, and more. Embedding StackOne into your own code? Implement Advanced Tool Search and the other discovery methods. # Data Sync Source: https://docs.stackone.com/optimize/data-sync/overview The engine that polls provider APIs on a schedule and stores the records in StackOne's indexes. Data Sync consumes credits from your allowance. See [plans and pricing](https://www.stackone.com/pricing/). Data Sync polls a provider on a schedule you set and stores the records it returns in a StackOne index. You don't read that index directly. [Deep Query](/optimize/deep-query) searches and aggregates the stored records for you, without calling the provider. You configure Data Sync once per action on a [Connector Profile](/gateway/concepts/connector-profiles). Every account on that profile is then synced automatically. ## How it works - You turn sync on for an action on a Connector Profile, and set how often it runs. - StackOne creates one sync per [Linked Account](/gateway/concepts/linked-accounts) on that profile, for accounts already linked and any linked later. - Each time a sync fires it is a **run**, which fetches records from the provider and writes them to the index. ## Turn on sync for an action In [Connectors](https://app.stackone.com/connectors), open the connector and select the profile's card. Data Sync is configured on a saved profile, not while you are creating one, and the action has to be switched on in that profile. On the **Actions** tab, actions that can be synced carry a **Data Sync** tag and a sync button next to their switch. Actions that need parameters to run, such as fetching one record by ID, can't be synced. 1. Click the sync button to open the **Data Sync** panel. 2. Turn on **Enable Data Sync**. 3. Set **Sync every** and **Full re-sync**. 4. To turn on sync for every action on the profile that supports it, turn on **Apply to all Actions**. To be notified about synced changes from the same panel, see [Data Sync Events](/optimize/data-sync/events). Click **Save Changes**. The first sync starts immediately for every Linked Account already on the profile. Data Sync panel for the List Unified Organizations action, with Enable Data Sync on, Sync every set to 1 day, Created, Updated and Deleted Events switches, a Deliver to webhook picker, and Apply to all Actions

Data Sync panel for the List Unified Organizations action, with Enable Data Sync on, Sync every set to 1 day, Created, Updated and Deleted Events switches, a Deliver to webhook picker, and Apply to all Actions

| Field | What it controls | Bounds | |-------|------------------|--------| | **Sync every** | How often StackOne fetches new and changed records. Actions that can't sync incrementally re-fetch everything on every run | 15 minutes to 365 days | | **Full re-sync** | How often StackOne re-fetches everything from scratch, to catch deletions and repair drift. Only shown for actions that support incremental syncs | At least 1 day, and less frequent than **Sync every** | Accounts linked after you save start syncing on their own first run, with no further configuration. You don't need to revisit the profile as your customers link accounts. ## Full and incremental runs Most runs are incremental, because they're cheap. Full runs happen on their own interval to catch what an incremental run structurally cannot. | | Incremental run | Full run | |---|---|---| | Fetches | Only records that changed since the last successful run, using a checkpoint the previous run left behind | Every record | | Runs | Every **Sync every** interval | The first run, then every **Full re-sync** interval, and whenever the connector's sync definition changes | | Writes | Into the current set of records, in place | A complete new set, swapped in only once the run succeeds, so a query never sees a half-written result | | Deletions at the provider | Not detected | Reflected | | If it fails | The checkpoint is unchanged, so the next run covers the same window again rather than skipping records | The previous records stay readable | Deletions only surface on a full run. A record deleted at the provider stays readable until the next full re-sync, because an incremental run has no way to learn that it's gone. Set **Full re-sync** to match how quickly you need deletions reflected. ## Monitor syncs Go to **Accounts**, open an account, and choose the **Data Sync** tab. Each synced action gets its own panel showing its cadence and when it next runs. Expand a sync to see its recent runs: whether each was full or incremental, how long it took, and how many records it created, updated, left unchanged, or deleted. The **Enabled** toggle is the one setting that's per-account. Turn it off to stop syncing an action for this account without touching the profile or any other account. | Run status | Meaning | |------------|---------| | `success` | The run finished and its records are readable | | `running` | The run is in progress. The previously synced records stay readable until it finishes | | `failed` | The run stopped on an error, shown in the row. The checkpoint is unchanged, so the next run retries the same window | | `truncated` | The run [stopped early](#runs-that-stop-early) at the page cap, or because the provider returned the same page twice | | `quota_exceeded` | The run [stopped early](#runs-that-stop-early), or didn't start, because the organization reached its record or storage [limit](#limits) | | `incomplete` | The run stopped without reporting a result. The next scheduled run resumes from the last checkpoint | A sync shows **Paused** when the action, or sync for that action, is switched off on the Connector Profile. Nothing runs until it's turned back on. ## Deeply nested data Data Sync stores every field a record has, however deeply it's nested, but [Deep Query](/optimize/deep-query) only indexes fields up to four levels deep. Each object a field sits inside counts as one level and each list of objects as two, so `address.city` is one level deep and `employment.history[].role` is three. Fields five or more levels deep, and lists of lists at any depth, are stored with the record without being indexed: - They come back with the record unless `source` leaves them out, and a change to one of them counts as a change to the record. - They can't be used to filter, sort, or aggregate. - A field five or more levels deep can still be named in `source`. The response then includes the whole nested object that holds it. Each record stores up to 64 KB of this unindexed data. Past that, the largest nested parts are left out of the stored record first. ## Data Sync events A sync can also send an event to a webhook for every record a run creates, updates, or deletes, so you hear about changes without querying for them. See [Data Sync Events](/optimize/data-sync/events). ## Limits | Limit | Default | |-------|---------| | Records stored per organization | 1,000,000 | | Storage per organization | 25 GiB | | Providers synced per organization | 100 | | Pages fetched in one run | 2,000 | | Duration of one run | 6 hours | | Record retention after the run that wrote it | 30 days | | [Deeply nested data](#deeply-nested-data) stored per record | 64 KB | The provider count means providers with at least one sync enabled, not actions. Syncing a second action on a provider you already sync costs nothing against it, and two Connector Profiles on the same provider count once. A connector can lower the per-run page and duration ceilings for an action that needs it, but never raise them. The page cap is usually hit first. In most cases, a run reaches 2,000 pages before it reaches 6 hours, so the duration ceiling is a backstop rather than the limit a run normally stops on. Turning on sync for an action fails if it would take the organization past 100 providers. The record and storage limits are checked as runs go, and a run that hits one stops early. Two more constraints are worth planning around rather than reading as numbers: - **Not every action can be synced.** Actions that need parameters to run, such as fetching one record by ID, have no sync. See [Turn on sync for an action](#turn-on-sync-for-an-action). - **Deletions wait for a full run.** Set **Full re-sync** to match how quickly you need them reflected. Records expire once that retention window passes without a run. Any enabled sync refreshes them well inside it, so expiry matters mainly for a sync you disable and leave off: its records drop out, and reads against them start reporting nothing synced. ### Runs that stop early A run stops early when it reaches the page cap, when the provider returns the same page twice, or when the organization reaches its record or storage limit. What happens next depends on the run: - **A full run is held.** Its records are discarded, the last complete sync stays readable, and no deletions are recorded. The next full run is attempted on the **Full re-sync** cadence. The run shows `truncated` or `quota_exceeded`. - **An incremental run keeps what it wrote**, but its checkpoint doesn't move, so the next run covers the same window again. Neither sends [events](/optimize/data-sync/events), so a day with an early-stopped run can have no events for that action. ## Next steps Search, filter, and aggregate the records a sync has stored. Where sync is configured, alongside actions and events. Send an event to a webhook for every record a run creates, updates, or deletes. # Data Sync Events Source: https://docs.stackone.com/optimize/data-sync/events Get notified at a webhook when a synced record is created, updated, or deleted, including for providers that have no webhooks of their own. [Data Sync](/optimize/data-sync/overview) can send an [event](/gateway/concepts/events) to a webhook for every record a run creates, updates, or deletes. StackOne works out the changes itself by comparing each run's records with the ones it already stored. Events are configured per action on a [Connector Profile](/gateway/concepts/connector-profiles), and every Linked Account with sync enabled for the action sends them. ## Turn on events for an action Events are delivered to a webhook in your project. If you don't have one yet, add it on the [Webhooks](/connect/webhooks#quickstart) page first, or create it from the connector page in step 4. Go to **Connectors**, open the connector, and select a saved Connector Profile. The action has to be switched on in that profile. Click the Data Sync icon on the action's row (**Set up Data Sync**). 1. Turn on **Enable Data Sync**, if it isn't on already. The event toggles stay disabled until it is. 2. Under **Events**, turn on **Created Events**, **Updated Events**, **Deleted Events**, or any combination. Select the webhook under **Deliver to**, or choose **+ Add Webhook** to create one. Click **Save Changes**. Events start with the next run of each Linked Account's sync. Subscribed actions show on the webhook's **Events** tab under **Connector**, tagged **Data Sync**, with a row for each change type. Each change type shows **Active**, or **Paused** when it's turned off or sync for the action isn't running. ## When events are sent Events go out once a run finishes, not the moment a record changes at the provider. How soon you hear about a change depends on **Sync every**. | Situation | What is sent | |-----------|--------------| | A Linked Account's first run | Nothing. The first run sets the baseline that later runs are compared with, so it sends no `created` event for the records that already existed | | The first run after sync was switched off for more than 30 days | Nothing. The stored records [expire after 30 days](/optimize/data-sync/overview#limits) without a run, so this run sets a new baseline, the same as a Linked Account's first run | | An incremental run | `created` and `updated` events for the records it fetched | | A full run | `created` and `updated` events, plus `deleted` for every previously stored record that is no longer at the provider | | A run that fails, or [stops early](/optimize/data-sync/overview#runs-that-stop-early) | Nothing for that run | | A record that didn't change | Nothing | | A change only in a [deeply nested field](/optimize/data-sync/overview#deeply-nested-data) | An `updated` event, as for any other field, unless that part was left out under the 64 KB per-record limit | `deleted` events only come from a full run, for the same reason [deletions only surface on one](/optimize/data-sync/overview#full-and-incremental-runs). Set **Full re-sync** to match how quickly you need to hear about deletions. ## Event payload The event name is the action ID followed by the change: - `{action_id}.created`: a record that wasn't in the stored set when the run started. - `{action_id}.updated`: a stored record whose fields changed since the last run. - `{action_id}.deleted`: a stored record a full run no longer found at the provider. For example, `bamboohr_list_employees.updated`. Each change is its own request to your webhook. | Field | Type | Description | |-------|------|-------------| | `event` | string | The event name, as above | | `project_id` | string | The project the Connector Profile belongs to | | `account_id` | string | The Linked Account the record was synced from | | `record_type` | string | The action ID | | `record_id` | string | The record's ID, taken from the field the action syncs on | | `event_date` | string (ISO 8601) | When StackOne prepared the event, after the run finished | | `sent_at` | string (ISO 8601) | When this delivery attempt was sent. Each retry gets a new value | | `event_data` | object | The full record as Data Sync stored it, the same shape Deep Query returns. Left out of `deleted` events, since the record is gone | ```json { "project_id": "proj_7f3a9c", "account_id": "acc_42d1e8", "event": "bamboohr_list_employees.updated", "event_date": "2026-09-29T09:15:02.114Z", "record_type": "bamboohr_list_employees", "record_id": "4127", "sent_at": "2026-09-29T09:15:02.530Z", "event_data": { "id": "4127", "first_name": "Ada", "last_name": "Lovelace", "work_email": "ada@example.com", "department": "Engineering" } } ``` `event_data` is read from the stored record when the event is prepared, after the run finishes. On a large run, preparing every event can take long enough for the next run to change the stored record first: - If the next run updates the record, the event carries the newer version. - If the next run removes the record, the event isn't sent, since there's no record left to send. ## Delivery Data Sync events are signed like every other webhook event, so the same [signature verification](/connect/webhooks#verifying-webhook-signatures) applies. Their delivery works as follows: - A delivery that doesn't get a `2xx` response is retried, starting after 5 seconds and backing off to every 10 minutes, for up to 20 attempts. - StackOne sends each change from a run once per webhook, and its own retries don't create duplicates. Your endpoint can still receive the same event twice if it returned `200` but the response was lost, so treat a repeat of the same `event`, `record_id`, and `event_date` as a duplicate. - Events arrive in batches and several are sent at once, so they aren't guaranteed to arrive in the order the records changed. Every delivery attempt is logged. **View logs** at the top of the webhook's page lists them. **View logs** on a Data Sync row in the webhook's **Events** tab opens that action's sync runs instead, with **Background Logs** turned on. ## Next steps Turn on sync for an action and set how often it runs. Create the webhook Data Sync events are delivered to, and verify their signatures. # Deep Query Source: https://docs.stackone.com/optimize/deep-query Search, filter, and aggregate synced records without calling the provider API. Deep Query searches, filters, and aggregates the records [Data Sync](/optimize/data-sync/overview) has stored, without calling the provider. Because it runs against StackOne's index rather than a third-party API, it's faster, consumes none of the provider's rate limit, and answers questions most provider APIs can't express at all. Deep Query covers any action that has a sync. Turn sync on for the action first, then everything below applies to it. ## Why query instead of calling the provider | | Live action call | Deep Query | |---|---|---| | Where it reads from | The provider, on every call | StackOne's index | | Provider rate limits | Every call counts against them | No provider request, so nothing counts | | Filtering | Only the query parameters that provider happens to expose | `term`, `terms`, `range`, `wildcard`, `match`, `match_phrase`, `exists`, and `bool` over any synced field up to four levels deep and outside lists of lists ([what is indexed](/optimize/data-sync/overview#deeply-nested-data)) | | Full-text search | Rarely offered | Free-text across every text field, ranked by relevance | | Aggregation | Not offered. Page through every record and count in your own code | One `aggs` query returns the numbers | | Field selection | Whatever the provider chooses to return | `source` returns only the fields you name | A query is billed like an action call. Listing queryable fields is not. ### Smaller responses, fewer tokens The last two rows are where an agent gains the most. Asking for three fields instead of forty shrinks the response the model has to read by the same proportion. Asking for a headcount by department returns a dozen numbers from one aggregation, where a live call means paging through every employee record and tallying them inside the context window. Deep Query and [Advanced Tool Search](/optimize/advanced-tool-search) work on the same budget from opposite ends: one shrinks what tool responses cost, the other shrinks what tool definitions cost. ## Query from an agent Once a sync has records, each synced action gains a companion tool named `{action}_s1query` - `bamboohr_list_employees_s1query` alongside `bamboohr_list_employees`. A `list_s1query_queryable_fields` tool tells the agent which fields it can filter and sort on. Both tools stay available, so the agent chooses: the Deep Query tool to search or aggregate across everything cheaply, the live tool when it needs the provider's current state. Records come back in the provider's own shape, with the provider's field names and nesting, not the normalized shape a regular action call returns. ## Try a query without code Open **Actions Request Tester** from the account page and pick the `(S1Query)` entry for the action. ## When to use it Use Deep Query when the same data is read repeatedly and tolerates being minutes to hours old, or when an agent needs to search or aggregate across the whole record set rather than page through it. For data that has to reflect the provider right now, call the [action](/gateway/concepts/actions) directly - both tools stay available to the agent. To be told when a synced record changes rather than querying for it, turn on [Data Sync events](/optimize/data-sync/events). Turn on the sync that Deep Query reads from, and set how often it refreshes. For developers querying the index from their own backend, with filters and aggregations. # Secure Source: https://docs.stackone.com/secure/overview Govern the connectors, members, access, and logs in your StackOne setup. Set up and govern how your team uses StackOne: connectors, members, access, and logs. Decide which tools your members' AI agents may use, which fields they see, which values they can send, and what data goes in and out, by user or group. Remove personal data from tool calls and from stored request logs. Choose which of a connector's actions and events each profile exposes. Choose who can link accounts through each connector profile. Manage your team, how they sign in, how they join, and which groups they belong to. Track activity and control how long data is kept. Run StackOne in your own environment for full data residency. How customer accounts stay isolated when you serve many clients from one setup. # Defender Source: https://docs.stackone.com/secure/defender Protect your AI agents from prompt injection attacks by scanning API tool call responses before they reach your LLM. **Defender** protects your AI agents from prompt injection attacks by scanning API tool call responses before they reach your LLM. When an MCP tool returns data from a third-party provider (emails, CRM records, documents), that data could contain instructions designed to hijack your agent's behavior. Responses are intercepted and classified by Defender, and depending on the **Protection Mode** you choose, Defender logs the verdict, removes high-risk content, or blocks the response before it reaches your agent. ## How it works

Defender's standard check is the **Light Scan**, two checks run together on every response: - **Pattern matching**: A fast rule-based scan for known prompt injection signatures and risky field patterns, with negligible latency. - **ML classification**: A local ML model (MiniLM) scores the content for novel or subtle attacks that pattern matching would miss. It scans the SFE-filtered payload (or the `tier2Fields` subset when configured), and reports its score as `tier2Score` in the response metadata. Responses that exceed the configured size limits can skip scanning entirely (see [Advanced settings](#advanced-settings)). The **Deep Scan** is a third check on top: an LLM reviews the response for risks the Light Scan misses. It runs only in StackOne's hosted service, not in the open source `@stackone/defender` package. The **Scan Mode** setting decides which responses get a Deep Scan (see [Scan mode](#scan-mode)). Risk level and scan metadata are returned alongside every response in every mode, so you can see what Defender detected even when it changed nothing. ## When to use Defender - You are building AI agents or MCP-based workflows that process third-party API responses - Your integrations handle sensitive data such as emails, files, calendar events, or CRM records - You want to observe risk signals on tool call responses without necessarily blocking them ## Configure from the dashboard Navigate to your project in the StackOne dashboard, then open the **Defender** tab in project settings. This is the baseline for every account in the project. ![Defender Settings](/images/defender-settings.png) Defender settings apply project-wide. Per-account and per-request overrides take precedence where supported. ### Core settings | Setting | Description | |---|---| | **Status** | Enables Defender scanning for this project. Default: **On** for new projects. | | **Protection Mode** | What Defender does with positive matches. See [Protection mode](#protection-mode). | | **Scan Mode** | How thoroughly responses are scanned. See [Scan mode](#scan-mode). | ### Protection mode | Mode | What happens to the tool result | |---|---| | **Monitor** (Default) | Observe only. Defender scans and adds its verdict to the logs. The tool result reaches your agent unchanged. | | **Sanitize** | Defender removes detected high-risk content from the tool result before your agent sees it. | | **Block** | Responses classified as high or critical risk are blocked and an error is returned to your agent. Lower risk responses are cleaned as **Sanitize** would handle them. | Start in **Monitor** to see what Defender would act on in your traffic by reviewing logs. Move to **Sanitize** or **Block** when you are ready to enforce. ### Scan mode | Mode | What it runs | When to choose it | |---|---|---| | **Light** (Default) | The Light Scan on every response. | Fastest. No response goes through the LLM review. | | **Hybrid** | The Light Scan on every response, plus a Deep Scan when the result is uncertain. | Adds the LLM review only where the Light Scan could not classify confidently. | | **Deep** | A Deep Scan on every response, skipping the Light Scan. | Most thorough. Every response gets an LLM review. | Light is the default. The Light Scan is the same open source engine as the `@stackone/defender` package; the Deep Scan runs only within StackOne's hosted service, so Hybrid and Deep are available here but not in the package. ### Protection level The protection level sets how sensitive the Light Scan is. | Level | What it catches | |---|---| | **Low** (Default) | Overt attacks only, such as "ignore your instructions". | | **Medium** | Overt attacks and some subtler injections. | | **High** | The most attacks, including subtle injections. | Higher levels catch more attacks but also flag more benign responses. Start on **Low** in **Monitor**, review the logs, then raise the level if attacks are getting through. ### Advanced settings | Setting | Description | Default | |---|---|---| | **Large Response Behavior** | What to do when a response exceeds the size limits: `Skip scanning` (default), `Block the response`, or `Scan anyway` | Skip scanning | | **Max Response Size** | Byte threshold that triggers large response behavior | 1,048,576 (1 MB) | | **Max Response Words** | Word count threshold that triggers large response behavior | 10,000 | | **Annotate Tool Results** | Wrap sanitized tool results with boundary tags such as `[UD-abc123]...[/UD-abc123]` (where the suffix is a random per-response ID) so downstream prompts can reason about data boundaries. Pair this with `generateBoundaryInstructions()` from `@stackone/defender` in your system prompt when enabled. | Off | ## Implement it Override Defender per toolset in the Agent SDK. ## FAQ It depends on when your project was created. New projects have Defender on. Older projects start with it off: turn it on from the **Defender** tab in project settings when your agents consume third-party data. Once on, it runs in **Monitor**, so tool results are unchanged until you choose **Sanitize** or **Block**. The Light Scan adds little: pattern matching is negligible, and the ML classifier runs locally, so there is no external API call. The Semantic Field Extractor trims metadata and identifier fields before classification to keep latency low; for typical responses the added latency is under 100ms. A Deep Scan adds an LLM review to the responses it covers, which costs more time than the local checks. The tool call returns an error to your agent indicating the response was blocked. The agent can handle this like any other tool error: retry, skip, or surface it to the user. Yes. That is what **Monitor** mode does, and it is the default. Defender still scans and returns `riskLevel`, `tier2Score`, and `detections` in the response metadata, which you can inspect in your logs, but the tool result reaches your agent unchanged. No. The Light Scan's classification model runs locally within StackOne's infrastructure, and the Deep Scan's LLM is a model StackOne deploys and operates on its own inference endpoints. Your responses are not sent to a third-party AI service, and neither model is trained on your data. # Scoping Connectors Source: https://docs.stackone.com/secure/scoping-connectors Scope what each connector can do: which of its actions and events are available. A [Connector Profile](/gateway/concepts/connector-profiles) holds the credentials and config for one connector in a [project](/gateway/concepts/organizations-and-projects). It's how you control which actions a connector exposes and how end-users link their accounts. This assumes you already have a connector profile. To create one, follow the [Quickstart](/gateway/quickstart) or pick a connector in [Connectors](/connectors/introduction), then return here. ## Enable or disable actions Scope a profile to just the actions your app uses. This limits what every linked account on the profile can do and keeps the OAuth consent screen focused. In [Connectors](https://app.stackone.com/connectors), open the connector and select the profile's card. Each action has a switch showing whether it's enabled for this profile. The switch in the table header turns every action on or off at once. Enable only the actions your app calls and disable the rest. We recommend starting with a few read actions, then enabling more as you need them. Click **Save Profile** in the bar at the bottom of the page. Changes apply to every linked account on the profile. **Cancel** discards them.

The **Library** card shows every action and event the connector offers, whatever any profile allows. Use it to browse a connector before you create a profile. ## Enable or disable events The **Events** tab lists every event this connector can emit. Turn on the events you want, and pick which webhook each one fires to from the dropdown alongside it, then click **Save Profile**. Choose **+ Add Webhook** in the dropdown to create a new webhook without leaving the page. The webhook is created right away and belongs to the project, so it stays even if you cancel the profile edits. See [Webhooks](/connect/webhooks) for the model and the difference between programmatic and manual events. A profile's Events tab with the Page Created event switched on and its webhook dropdown open, listing project webhooks and an Add Webhook option

Events tagged **Requires Setup** are manual events. They only fire once the StackOne webhook URL is registered in the provider's own platform. The connector's guide in [Connectors](/connectors/introduction) covers the provider side. # Tool Policies Source: https://docs.stackone.com/secure/policies Set agent tool policies to control which tools your agents use, which fields they see, and what data goes into and out of each call. Tool Policies is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). **Tool Policies** control which tools an agent may use, and how, on behalf of the member it acts for. StackOne checks the policies that apply to that member before a tool call reaches the provider, and refuses the call when an enforced policy denies it. Value rules, semantic rules and PII checks also look at the data itself. Value rules check the argument values a tool receives before it executes. Semantic rules and PII checks run on the tool's inputs before it executes and on the response before the agent sees it.

Flow diagram with three lanes. An AI agent makes a tool call and Tool Policies are checked. Allowed: the provider is called and the response returns unchanged. Redact PII or Read a field: the provider is called and the response returns with PII redacted or fields masked. Denied, including Write a field denials: the provider is not called and a refusal is returned. All three responses come back to the AI agent. A note under the diagram says semantic rules and PII checks run on both the inputs and the response

## How a policy is evaluated A policy carries a single **rule** that allows or denies capabilities. Rules are made up of 4 parts: | Part | Options | What it means | | --- | --- | --- | | **Who it applies to** | **Everyone**, **Users**, **Groups** | The members whose agents the rule governs. Groups come from [Manage Groups](/secure/identity-and-access/roles-and-groups/groups). | | **What it does** | **Allow**, **Deny** | A deny rule refuses exactly what it covers for those users or groups. An allow rule restricts nothing and cannot undo a deny. | | **Capabilities** | **Use a tool**, **Read a field**, **Write a field**, **Value rule**, **Redact PII**, **Semantic rule** | The operations the rule covers. One capability per kind of access, each narrowed on its own terms. See [Capabilities](#capabilities) below. | | **Applies to** | **Everything**, **A connector category**, **A connector**, **An account**, **Specific tools** | Where the capability is covered. **Tools matching** narrows any target with a name pattern. | Four guarantees hold across every policy: When policies overlap, a matching deny refuses the call whatever any allow says. [Connector Profile scoping](/secure/scoping-connectors) and [account access](/secure/identity-and-access/roles-and-groups/connector-profile-access) apply restrictions before policies. Policies apply when the member is known, which is the case for [AI platform](/connect/overview) sessions. A call made with a project API key is memberless — govern that traffic with [Connector Profile scoping](/secure/scoping-connectors) instead. A policy belongs to the project it is created in and governs calls made in that project only. To apply the same rule in several projects, create it in each. ### Capabilities A **capability** is the kind of access a rule governs: running a tool, reading or writing a field, passing an argument value outside the range or list you set, passing PII through a call, or sending and receiving data that a semantic rule's question flags. Denying one removes that access for the users or groups the rule covers. | Capability | What denying it does | | --- | --- | | **Use a tool** | Refuses the call. The agent may not run the tool at all. | | **Read a field** | Masks the field in responses. | | **Write a field** | Refuses calls that would change the field. | | **Value rule** | Refuses calls whose argument values fall outside the condition, such as a payment amount outside 25 to 500 USD. Calls with values inside it keep their existing access. | | **Redact PII** | Finds the chosen classes of PII (email addresses, phone numbers, SSNs, or credit card numbers) in the tool's inputs and responses, then redacts the detected span or blocks the call. Record UUIDs, order numbers, and API keys stay intact. See [PII Redaction](/secure/pii-redaction). | | **Semantic rule** | Asks a plain-language question about the data in the call. On inputs, a matching answer refuses the call before the tool runs. On a response, it masks the field the answer applies to. | Rules can carry more than one capability. Capabilities are alternatives rather than conditions: the rule applies where **any** one of them matches, so adding a second says "or also" rather than narrowing the first. Each is scoped on its own terms, so one rule can deny a tool outright on one connector and only mask a field on another. ## Create a policy Select the project, open [**Project Settings > Policies**](https://app.stackone.com/settings/policies), and click **Create policy**. Give the policy a descriptive name. Choose an **Enforcement** level: - **Enforced**: Refuses calls the policy denies, masks fields, and blocks or redacts data according to the rule. - **Monitored**: Records decisions in the logs without blocking or modifying calls. - **Disabled**: Stores the policy without evaluating it. Start new deny rules in **Monitored**, verify the decisions in your logs, then switch to **Enforced**. Select **Everyone**, **Users**, or **Groups**, then search for the users or groups the rule covers. Select **Deny** to refuse the capability for those users or groups, or **Allow** to state permitted use without restricting anything. Add the [capabilities](#capabilities) the rule governs: Denying **Use a tool** refuses the call. Choose which targets it applies under **Applies to**: - **Everything** covers every tool in the project. - **A connector category** covers every tool on every connector in the category, including connectors added later. - **A connector** covers every tool on the connectors you pick. - **An account** covers the tools of specific [Linked Accounts](/gateway/concepts/linked-accounts). Search accounts by name or owner. - **Specific tools** lets you pick a connector, then the tools on it by name. To narrow the tools covered by the target selection, enter a name pattern under **Tools matching** (see the pattern syntax below). An empty pattern covers every tool the targets include, so a deny refuses every call to them. A capability takes either specific tools or a pattern, not both. Denying **Read a field** masks the field in responses. Choose which targets it applies under **Applies to**: - **Everything** covers every connector and account in the project. - **A connector category** covers every connector in the category, including ones added later. - **A connector** covers the connectors you pick. - **An account** covers specific [Linked Accounts](/gateway/concepts/linked-accounts). Search accounts by name or owner. To narrow the fields covered by the target selection, enter a pattern on the field's path in the response under **Fields matching** (see the pattern syntax below). An empty pattern covers every field the targets include, so a deny masks every field in scope. Denying **Write a field** refuses calls that would change the field. Choose which targets it applies under **Applies to**: - **Everything** covers every connector and account in the project. - **A connector category** covers every connector in the category, including ones added later. - **A connector** covers the connectors you pick. - **An account** covers specific [Linked Accounts](/gateway/concepts/linked-accounts). Search accounts by name or owner. To narrow the fields covered by the target selection, enter a pattern on the field's path under **Fields matching** (see the pattern syntax below). An empty pattern covers every field the targets include, so a deny refuses every call that would change one. Denying **Value rule** keeps a tool available and checks the values the agent passes in its arguments. Choose which targets it applies under **Applies to**, the same way as **Use a tool**, then pick the argument and the condition its value must meet: - **A range** for numbers, such as a payment amount between 25 and 500 with the currency `USD`. - **Allowed or blocked values**, such as an invoice status that may be `Draft` or `Submitted` but not `Authorized`, or a sharing type that may not be `anyone`. A call whose value falls outside the condition is refused before the tool runs. A call that leaves the argument out, or sends it in another type or currency, is refused too. Denying **Redact PII** checks calls for the chosen classes of PII. StackOne's own PII model scans the tool's inputs before it runs and the response before the agent sees it, including free-text fields such as ticket bodies and notes. Record UUIDs, order numbers, and API keys stay intact. The [PII Redaction benchmark](https://www.stackone.com/platform/pii-redaction/#benchmarks) compares the model with Microsoft Presidio on connector data. Choose which targets it applies under **Applies to**: - **Everything** covers every connector and account in the project. - **An account** covers specific [Linked Accounts](/gateway/concepts/linked-accounts). Search accounts by name or owner. Under **Which PII to redact**, select one or more classes. There is no pattern to enter. Then choose what a detection does: - **Redact** replaces each detected span in the inputs and in the response, and lets the call continue. The rest of the input or response is unchanged. - **Block** refuses the call. When the PII is in the inputs, the provider is never called. When it is detected in the response, the agent receives a refusal instead of the data. A response that cannot be scanned (it is streamed, above the scan size limit, or the scan fails) is returned unredacted, and the request log records which classes were not redacted. For how detection works, what changes in the call and what is recorded, see [PII Redaction](/secure/pii-redaction). Denying **Semantic rule** asks a decision model a question about each call in scope. Write the question in plain language, for example: > Does this message contain unreleased financial results? The model answers for each field or payload, so the rule holds whatever a connector calls the field. Choose which targets it applies under **Applies to**, the same way as **Use a tool**. For a rule about outgoing messages, pick the send tools on the connectors that matter, such as Slack, Gmail and Notion. Then choose where the question is asked: - **Inputs**: a matching answer refuses the call before the tool runs. - **Response**: a matching answer masks the field it applies to before the agent sees it. A field the model cannot decide is masked unless the rule allows it.
- `*` is the only wildcard, and it matches any run of characters. - A pattern has to cover the whole name: `salary` matches only something named exactly that, so use `*salary*` to match it anywhere. - Matching is case-sensitive. - `?`, `[a-z]`, and `{a,b}` are ordinary characters here, not wildcards. A pattern using one saves cleanly and then never matches anything. | Pattern | Matches | Does not match | | --- | --- | --- | | `*delete*` | `personio_delete_person` | `okta_remove_user_from_group` | | `salary` | `salary` | `employee.compensation.salary` | | `*Delete*` | Nothing, since matching is case-sensitive. | `personio_delete_person` | For a deny rule, use **Exempt from this rule** to name users or groups the rule does not apply to. Another matching deny can still refuse the call. Review the policy: - **Plain Text**: the panel footer restates the rule in plain words, for example: > Everyone in this project may not use a tool matching `*delete*` on Workday, except Finance (Group). - **Cedar**: the exact statement the engine will evaluate, in [Cedar syntax](https://docs.cedarpolicy.com/policies/syntax-policy.html). The view is read-only; change the form and the statement follows. - **JSON**: the same statement in Cedar's JSON encoding. Then click **Create policy**. If you used the assistant, the button reads **Accept changes and create**. See [Build a policy with the Policy AI Assistant](#build-a-policy-with-the-policy-ai-assistant). Create policy panel with Policy chat on the left and the form on the right, showing a policy named Contractors cannot use tools that delete records, the audience set to the Contractors group, and a Deny rule on the Use a tool capability

Create policy panel with Policy chat on the left and the form on the right, showing a policy named Contractors cannot use tools that delete records, the audience set to the Contractors group, and a Deny rule on the Use a tool capability

## Build a policy with the Policy AI Assistant The **Policy AI Assistant** opens beside the form, as **Policy chat**, whenever you create or edit a policy. Describe the rule in your own words and the assistant drafts it in the form for you to review: - Suggestions are highlighted in the form, with the previous value shown underneath. - Each suggestion can be applied or reverted individually. - All changes can be applied using the buttons at the top of the form or by clicking **Accept changes and create** or **Accept changes and save**. The assistant drafts every capability, including value rules, semantic rules and PII redaction. Ask for *Keep unreleased financial results out of Slack for everyone outside Finance* and it writes the semantic rule's question, picks the send tools, and sets the audience and exemption. Create policy panel split in two, with Policy chat on the left showing completed search_principals and update_policy_draft tool calls and an explanation of the proposed rule, and the policy form on the right with a bar reading 3 changes from the assistant need review

Create policy panel split in two, with Policy chat on the left showing completed search_principals and update_policy_draft tool calls and an explanation of the proposed rule, and the policy form on the right with a bar reading 3 changes from the assistant need review

### What the assistant can access The assistant can look things up in the project as it drafts, and the transcript shows each lookup as it runs: | It can find | So you can say | | --- | --- | | Users and groups | *Exempt payroll*, (where you have a group defined as "payroll") | | Connectors and categories | *Block writes to any HRIS connector* | | The tools on a connector | *Stop the delete ones on Workday* | | Linked accounts | *Only the Acme production account* | | Related tool call logs | *Stop this tool returning some of the fields it returned* | By default, only a tool call's tool, connector and caller are exposed. With [advanced logging](/secure/observability#advanced-logs) enabled, the assistant can read the request/response payloads to help define field related capabilities. For example, using a prompt like: > Stop contractors deleting records 1. The assistant searches existing groups, sets **Who it applies to** to `Groups` and populates with `Contractors`. 2. Writes a deny on **Use a tool** with a `*delete*` pattern, with **applies to** set to `Everything`. The assistant also flags what a rule may miss. For example, a pattern matching `delete` does not catch a connector whose tools are named with `remove` or `archive`, so you can ask it to add those patterns too. ### Starting from logs Policy creation can be initiated from a specific log instead of the policies page. Go to [StackOne Logs](https://app.stackone.com/logs). Select the log of a call you want to create a policy from. Click **Use in policy** at the top of the panel. This takes you to the **Policies** page with the context of the log selected. Either select an existing policy **OR** create a new policy by clicking **Create policy**. The **Policy AI Assistant** now has the context of the selected log. Describe the policy you want. For example: > *This call should not have been allowed to return salary* > *This person should not have been allowed to make it* See [Build a policy with the Policy AI Assistant](#build-a-policy-with-the-policy-ai-assistant). ## Testing a policy before enforcing it Two checks come before enforcing: 1. **Test against personas**: in the create and edit panel, **Test this policy against personas** shows what the rule would decide for the members you choose, without making a call. 2. **Monitored**: set the policy's **Enforcement** to **Monitored** and applicable tool calls are flagged as calls the policy would have applied to, while continuing unaffected. Value rule matches, semantic rule answers and PII detections are recorded the same way. Only when **Enforcement** is set to **Enforced** are tool calls blocked or modified as defined by the policy. ## Change a policy's enforcement level The **Policies** table displays an **Enforcement** column showing each policy's current level: **Enforced**, **Monitored**, or **Disabled**. Select the project and open [**Project Settings > Policies**](https://app.stackone.com/settings/policies). On the policy's row in the table, click the **...** button and select the new level: - **Enforce** moves the policy to **Enforced**. - **Monitor** or **Stop enforcing** moves the policy to **Monitored**. - **Disable** moves the policy to **Disabled**. You can also edit the policy and change the **Enforcement** field in the side panel. ## Duplicating policies Instead of starting with a blank new policy, an existing policy can be used as a template. Select the project and open [**Project Settings > Policies**](https://app.stackone.com/settings/policies). On an existing policy's row in the table, click the **...** button and select **Duplicate**. A new policy is drafted with the original policy's details except: - **Name**: original name is appended with `(copy)`. - **Enforcement**: set to **Disabled**. Edit as needed, then click **Create policy**. A policy whose rule the builder cannot read, or that holds more than one statement, cannot be duplicated. ## Examples One **Use a tool** deny with **Applies to** set to **Everything** and **Tools matching** set to `*delete*`, for the `Contractors` group. Run it in **Monitored** first, check the logged decisions, then switch it to **Enforced**. A **Value rule** deny on the payment tools for NetSuite and Xero, on the payment amount, allowing amounts between 25 and 500 in `USD`. A payment outside that range, or in another currency, is refused before the tool runs, and payments inside it go through as before. A **Semantic rule** deny on the send tools for Slack, Gmail and Notion, asking *Does this message contain unreleased financial results?* on **Inputs**. It applies to **Everyone**, with the `Finance` group exempt. The agent can still summarize the month-end close for Finance, and a message that posts those numbers to a shared channel is refused. Two policies for the support agent's users: - **Zendesk**: a **Redact PII** deny on the Zendesk account, set to **Redact**, so responses reach the agent without email addresses, phone numbers or card numbers. The same policy adds **Read a field** on Zendesk, with **Fields matching** set to the card number's path, so that field is always masked. - **Jira and Slack**: a **Redact PII** deny on the Jira and Slack accounts, set to **Block**, so a write that contains PII is refused. The agent can still escalate the bug to Jira, without the customer's details. ## What a denied call returns When an enforced policy refuses a tool call before it runs, the request fails with HTTP `403` and nothing reaches the underlying provider. The refusal returns to the agent as the tool result. ```json { "message": "Action 'personio_delete_person' is not permitted by project policy", "errorType": "POLICY_DENIED_ERROR", "level": "project" } ``` A call refused by a value rule, a semantic rule or a PII block on its inputs fails the same way, before the provider is called. A PII block on a response refuses the call after the provider responds: the agent receives the refusal instead of the data. Masking and redaction on a response never fail the call: the agent receives the response with the denied fields masked and the detected spans redacted. ## Troubleshooting - **It matches nothing.** The pattern has to cover the whole name: `salary` only matches a tool named exactly that, so use `*salary*`. `?`, `[a-z]`, and `{a,b}` do not perform any special matching. - **It misses tools you expected.** Matching is case-sensitive: `*Delete*` misses `personio_delete_person`. A pattern matches exactly rather than describing a behavior: `*delete*` does not catch a tool named `okta_remove_user_from_group`. - **It matches more than you expected.** `*` matches any run of characters, underscores included, so `*create*` could cover `leaddocket_list_opportunities_created_since`. Check the following in order: 1. The policy's **Enforcement** is set to **Enforced** (not **Monitored** or **Disabled**). 2. The acting member is in its audience (and not exempt). 3. The call is made in the project the policy was created in. 4. The tool name or pattern matches exactly, including case. 5. The caller is a member connected through an [AI platform](/connect/overview), so the call carries their identity. A call made with a project API key alone names no member, so no policy governs it. Yes, on an action log. Open the record and select the **Policy** tab. ## Next steps Set which actions each Connector Profile exposes. Maintain the groups your policies apply to. Control who can link accounts on a profile. Configure request logging and retention. # PII Redaction Source: https://docs.stackone.com/secure/pii-redaction Remove personal data from tool inputs and responses, and from request and response bodies before Advanced Logs stores them. **PII Redaction** finds personally identifiable information (PII), such as email addresses and phone numbers, in the data passing through StackOne and replaces each value with a tag such as ``. It runs in two places, each turned on separately. A **Redact PII** rule in [Policies](/secure/policies) cleans what the agent sends to a tool and what the tool returns. The **Redact personal information (PII)** setting in [Advanced Logs](/secure/observability#advanced-logs) cleans request and response bodies before they are stored. ```mermaid graph TD Call["AI agent calls a tool"] --> RuleIn["Redact PII rule redacts or blocks the input"] RuleIn --> Action["StackOne runs the action"] Action --> Provider["Provider responds"] Provider --> Defender["Defender scans the response"] Defender --> RuleOut["Redact PII rule redacts or blocks the response"] RuleOut --> Receive["AI agent receives the response"] Action -.->|request and response bodies| LogScan["Advanced Logs PII redaction"] LogScan --> Log["Stored advanced log"] style Call fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151 style Receive fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151 style Provider fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151 style Action fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style Defender fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af style RuleIn fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff style RuleOut fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff style LogScan fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff style Log fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151 ``` ## Choose where to redact The two surfaces are independent, so a project can use either or both. | | **Redact PII** rule in Policies | **Redact personal information (PII)** in Advanced Logs | | --- | --- | --- | | **Protects** | The inputs your agent sends to a tool and the responses the tool returns. | The request and response bodies Advanced Logs stores. | | **Classes** | The ones you select: **Email address**, **Phone number**, **Social security number**, **Credit card number**. | Every kind of personal data the scan detects, including names, phone numbers, email addresses, postal addresses, government ID numbers, and payment card numbers. | | **Kept intact** | Everything outside the selected classes, including record UUIDs, order numbers, and API keys. | Log metadata such as the path, status code, connector, and Linked Account. | | **Scope** | The whole project, or specific Linked Accounts. | The whole project. | | **Calls covered** | Calls made by the users or groups the policy covers, through an [AI platform](/connect/overview). | Every call that writes an advanced log of an action. | | **On a match** | **Redact** replaces the value. **Block** refuses the call, whether the match is in the inputs or the response. | The value is replaced. | | **Rollout** | **Monitored** records what the rule would do, then **Enforced** acts. | On or off. | | **Configured in** | **Project Settings > Policies** | **Project Settings > Advanced Logs** | ### Redact PII and semantic rules **Redact PII** and the **Semantic rule** capability both use a model to work out what the data in a call contains, then apply your policy to it, on a tool's inputs and its response. A semantic rule answers a plain-language question you write. **Redact PII** looks for four fixed classes of PII with StackOne's own model, and finds them inside any field, including free text such as a ticket description. See [Capabilities](/secure/policies#capabilities) for both. ## How detection works StackOne scans every string value in the body, in two passes: 1. **Patterns** match well-formed values such as email addresses. 2. **StackOne's PII model**, a token classifier StackOne trained for this task, reads the text for personal data the patterns miss, such as a phone number inside a ticket comment. The model is about 24MB and runs inside StackOne's runtime, in the process that runs the action. Your data is not sent to a third-party detection service, and detection adds milliseconds rather than a network call. Only the matched span is replaced, so a ticket description keeps its text and loses the email address inside it. On a tool input, redaction runs before the call reaches the provider. On a response, it runs after [Defender](/secure/defender) has scanned the response, and before the agent receives it. ## Redact PII in tool calls A **Redact PII** rule is a [policy](/secure/policies) capability. Denying it for a class redacts that class from tool inputs and responses, or blocks any call where it appears. Every class you don't select passes through unchanged, so a customer number or record UUID next to a redacted email address stays as it was. 1. Select the project and open **Project Settings > Policies**. 2. Click **Create policy** and give the policy a descriptive name. 3. Set **Enforcement** to **Monitored**. 1. Under **Who it applies to**, select **Everyone**, **Users**, or **Groups**, then pick the users or groups. 2. Under **What it does**, select **Deny**. Under **Capabilities**, add **Redact PII**. Denying **Redact PII** checks calls for the chosen classes of PII. StackOne's own PII model scans the tool's inputs before it runs and the response before the agent sees it, including free-text fields such as ticket bodies and notes. Record UUIDs, order numbers, and API keys stay intact. The [PII Redaction benchmark](https://www.stackone.com/platform/pii-redaction/#benchmarks) compares the model with Microsoft Presidio on connector data. Choose which targets it applies under **Applies to**: - **Everything** covers every connector and account in the project. - **An account** covers specific [Linked Accounts](/gateway/concepts/linked-accounts). Search accounts by name or owner. Under **Which PII to redact**, select one or more classes. There is no pattern to enter. Then choose what a detection does: - **Redact** replaces each detected span in the inputs and in the response, and lets the call continue. The rest of the input or response is unchanged. - **Block** refuses the call. When the PII is in the inputs, the provider is never called. When it is detected in the response, the agent receives a refusal instead of the data. A response that cannot be scanned (it is streamed, above the scan size limit, or the scan fails) is returned unredacted, and the request log records which classes were not redacted. Review the rule in the panel footer, then click **Create policy**. Under **Monitored**, PII detections are recorded and the call goes through unchanged. Run real calls, then open an action log and select the **Policy** tab to review the record. Once the rule catches what you expect, edit the policy, set **Enforcement** to **Enforced**, and save. The rule acts from the project's next call. For every option on the policy form, see [Create a policy](/secure/policies#create-a-policy). ### What changes in the call With **Redact**, each match is replaced by a tag naming its class, such as ``, in the input the provider receives or the response the agent receives. The agent can tell a value was withheld by policy, and which class it was. With **Block**, the agent receives a [refusal](/secure/policies#what-a-denied-call-returns) as the tool result. If a chosen class is in the inputs, the provider is never called. If it is detected in the response, the agent gets the refusal instead of the data. When a rule removed something, the tool result also carries `policyMetadata`. Its `result` is `partial`, and `redactedClasses` names each class removed and the policy level, not the rule. For example, a response from which an email address was removed: ```json { "isError": false, "result": { "data": { "id": "8f2c1a7e-4b6d-4e3a-9c1f-2d7b5e0a3c91", "description": "Refund request. Email ." } }, "policyMetadata": { "result": "partial", "maskedFields": [], "redactedClasses": [ { "class": "email", "level": "project" } ] } } ``` The class values are `email`, `phone_number`, `ssn`, and `credit_card`. ## Redact PII in Advanced Logs Select the project and open **Project Settings > Advanced Logs**. 1. Turn **Status** on, if it is off. The other settings can only be changed while it is on. 2. Turn on **Redact personal information (PII)**. ![Advanced Logs settings: status, storage, background operations, and PII redaction](/images/project-advanced-logs.png) When **Redact personal information (PII)** is on, StackOne scans each body before the log is written and replaces each personal value it detects with a tag naming its type, such as `` or ``. Credential-like tokens the patterns catch have no type and become ``; named credential fields follow the **Credentials** rule below. Only the redacted copy is stored. - **Detection.** Patterns catch email addresses and credential-like tokens. A model finds names, phone numbers, postal addresses, government ID numbers, payment card numbers, and other personal data. - **Scope.** Request and response bodies only. Log metadata such as the path, status code, connector, and Linked Account stays intact, so logs remain searchable. - **Coverage.** The bodies of action call logs. - **Applies to new logs only.** Logs that are already stored are not changed. - **Credentials.** Fields whose names match a fixed list of credential names, such as `password`, `token`, `api_key`, `client_secret`, and `authorization`, are masked in every stored body whether or not PII redaction is on. The value is replaced with `**redacted**`, followed by its last five characters when it is longer than 10 characters. StackOne may not catch every instance of personal data. Don't treat redaction as the only control for regulated data. For the other Advanced Logs settings, see [Observability](/secure/observability#advanced-logs). ## What is recorded Each surface leaves a different trace: - **Redact PII rule.** Open the action log and select the **Policy** tab. A call the rule changed is recorded with result `partial`, and the rule that acted shows the effect `redacted`. Under **Monitored**, the record shows the PII the rule detected instead. - **Advanced Logs.** The stored body is the redacted copy. Nothing records which values were replaced. ## FAQ No. Both passes run inside StackOne's runtime, in the process that runs the action. No third-party detection service sees your data. On connector data, detection takes about a millisecond per field at the median, measured for detection alone on 4 CPU cores. Longer text, such as a full document, takes longer. Detection runs in the process that runs the action, so there is no extra network call. A **Redact PII** rule removes only the classes you select, and record UUIDs, order numbers, and API keys belong to none of them. The Advanced Logs setting detects them in stored bodies. The **Redact PII** rule covers the four classes listed in [Choose where to redact](#choose-where-to-redact). To keep a field such as a home address away from the agent, deny **Read a field** on it in a [policy](/secure/policies#capabilities). Span-level F1 score compared with Microsoft Presidio, on 247 Connector PII examples and 1,000 examples for each other dataset: | Dataset | StackOne | Presidio | | --- | --- | --- | | OpenPII (synthetic prose) | 89.3% | 67.3% | | Nemotron-PII (business documents) | 95.5% | 69.4% | | Privy (JSON, SQL, and XML payloads) | 98.9% | 51.3% | | Connector PII (connector field values) | 97.9% | 68.1% | On 129 connector field values with no personal data, StackOne's model flagged 3.1% as PII, and Presidio flagged 48.8%. The OpenPII row uses 1,000 English validation rows of [OpenPII 1.5M by Ai4Privacy / Ai Suisse SA (CC BY 4.0)](https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1.5m). All rows were measured in October 2026. StackOne's model was trained on the training splits of Nemotron-PII and Privy and on connector data, among other sources, and never on OpenPII. Connector PII is StackOne's own dataset. No test example appears in the training data. ## Next steps Combine Redact PII with tool and field rules for the same users. Configure Advanced Logs storage and retention. Scan tool responses for prompt injection. Limit which actions each Connector Profile exposes. Benchmark and examples. # Identity and Access Source: https://docs.stackone.com/secure/identity-and-access/overview Manage how your team signs in to StackOne and what each person can access. Enable your users to start using StackOne: Set up how users sign in. Use Single Sign-On (SSO) so users sign in through your identity provider (IdP), or keep passwords with MFA. Choose how users join and leave. Invite users, add them at their first SSO sign-in with Just-in-Time Provisioning, or sync them from your IdP's directory with SCIM Provisioning. Give users the access they need. Assign each user a role, from the whole organization down to a single linked account. Use groups to give many users the same project or account access. # Authentication Source: https://docs.stackone.com/secure/identity-and-access/authentication/overview Set up Single Sign-On with an identity provider, or use passwords with multi-factor authentication. StackOne can be set up to let users sign in with Single Sign-On or with a password and MFA. Connect the SAML identity provider and verify the domain so users sign in through the IdP. Change your password, turn on MFA, and require MFA for the whole organization. # Single Sign-On Source: https://docs.stackone.com/secure/identity-and-access/authentication/sso/overview Let users sign in to StackOne through your organization's SAML identity provider. SAML SSO is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). StackOne Single Sign-On (SSO) lets the organization's users sign in through its own SAML 2.0 identity provider (IdP). StackOne acts as the SAML service provider (SP), and the IdP authenticates users. Each organization has one SSO connection, bound to one email domain. Once that domain is verified, anyone whose work email is on it signs in through the IdP instead of with a StackOne password. They can start from the StackOne sign-in page by entering their email, or open the StackOne app from the IdP. Signing in with SSO doesn't add anyone to the organization. To add users, see [Manage Team](/secure/identity-and-access/manage-team/overview). ## Set up an SSO connection The guide for your SAML IdP takes you through each part of the setup: - Creating the SAML app in the IdP. - Registering it in StackOne. - Verifying the domain. - Managing the connection afterward. ## Require SSO Once the domain is verified, you can require users to sign in through SSO and turn off email and password sign-in. Enforcing doesn't check that sign-in works. A misconfigured SAML app, an unassigned user, or a certificate or issuer mismatch still enforces, and **anyone the IdP can't authenticate is locked out**. Before you enforce, open a private or incognito window and complete an SSO sign-in as a user assigned to the app in the IdP, not only your own account. 1. Go to [**Organization > Security > Authentication**](https://app.stackone.com/organization/security/authentication). 2. On the **Enforcement Policy** card, select **Edit policy**. 3. Add the SAML connection to **Enforced methods**. 4. Select **Save changes**. The Enforcement Policy panel under Organization > Security > Authentication, where you add the SSO connection to the enforced sign-in methods.

The Enforcement Policy panel under Organization > Security > Authentication, where you add the SSO connection to the enforced sign-in methods.

Enforcement takes effect as soon as you save. Anyone whose session didn't come through an enforced method, including you, is asked to sign in through the IdP the next time they load a page or switch to the organization. Locked out after enforcing? An **Organization Admin** who can still reach the dashboard can remove the method from the **Enforcement Policy** to restore password sign-in. If no one can get in, contact StackOne support. ## Next steps Add users who aren't members yet when they sign in, and map an attribute to organization admin. Provision and deactivate members automatically from the IdP. Grant many members the same project or account access at once. # Okta SSO Source: https://docs.stackone.com/secure/identity-and-access/authentication/sso/okta Set up SAML Single Sign-On between Okta and StackOne. SAML SSO is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Connect Okta as the organization's SAML 2.0 identity provider (IdP), so users sign in to StackOne with their Okta credentials. Before setting up Okta SSO, you need: - The **Organization Admin** role in StackOne. - Administrator access to the **Okta Admin Console**. - The ability to add a DNS TXT record for your email domain, which proves you own it. ## Start the connection in StackOne 1. Go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Click **Get started**. 3. Select **Okta** as the provider. On the **Connection details** step, fill in both fields: - **Connection name**: a name for the connection. StackOne generates the connection's unique ID from it. - **Domain**: the email domain your users sign in with. The **Configure your identity provider** step has the values you need when you create the app in Okta: - **ACS URL (Single sign-on URL)**: where Okta posts the SAML assertion. - **Audience URI (SP Entity ID)**: identifies StackOne to Okta. - **Default RelayState**: the dashboard URL, where an IdP-initiated sign-in lands. Keep this StackOne tab open. You return to the wizard to register the provider after you build the Okta app. StackOne Configure step showing the ACS URL and SP Entity ID to copy into Okta

StackOne Configure step showing the ACS URL and SP Entity ID to copy into Okta

## Create the SAML app in Okta 1. In the **Okta Admin Console**, go to **Applications > Applications**. 2. Click **Create App Integration**. 3. Choose **SAML 2.0**. 4. Click **Next**. Okta Create App Integration dialog with SAML 2.0 selected

Okta Create App Integration dialog with SAML 2.0 selected

1. On **General Settings**, enter an **App name**, for example `StackOne SSO`. 2. Click **Next**. Okta general settings page with the app named StackOne SSO

In **Configure SAML**, set the following: - **Single sign-on URL**: the **ACS URL** from StackOne. - **Audience URI (SP Entity ID)**: the **SP Entity ID** from StackOne. - **Default RelayState**: the **Default RelayState** from StackOne. - **Name ID format**: `EmailAddress`. - **Application username**: `Email`. Okta SAML settings filled with the StackOne ACS URL, Audience URI, EmailAddress Name ID, and Email username

Okta SAML settings filled with the StackOne ACS URL, Audience URI, EmailAddress Name ID, and Email username

1. Further down the same **Configure SAML** screen, under **Attribute Statements (optional)**, add two attributes: | Name | Name format | Value | |------|-------------|-------| | `givenName` | `Unspecified` | `user.firstName` | | `surname` | `Unspecified` | `user.lastName` | These set the user's display name in StackOne. 2. Click **Next**. 3. Click **Finish**. Adding these to an existing app only sets names for new users. To sync names for existing users, use [SCIM Provisioning](/secure/identity-and-access/manage-team/scim/okta). 1. Open the **Assignments** tab. 2. Assign the people or groups who should sign in to StackOne through Okta. Only assigned users can complete SSO. Okta Assignments tab for adding users to the StackOne SSO application

Okta Assignments tab for adding users to the StackOne SSO application

Open the app's **Sign On** tab, then get the values StackOne needs. Download the **Identity Provider metadata** XML. 1. In the **SAML Setup** panel, click **View SAML setup instructions**. 2. Copy these values for StackOne: - **Identity Provider Issuer**: the Entity ID, for example `http://www.okta.com/exk...`. - **Identity Provider Single Sign-On URL**: Okta's login endpoint. - **X.509 Certificate**: the signing certificate in PEM format. Okta Sign On tab showing the Identity Provider Issuer, SSO URL, and X.509 certificate

Okta Sign On tab showing the Identity Provider Issuer, SSO URL, and X.509 certificate

## Register the provider in StackOne Switch back to the StackOne tab and continue to the **Register your SSO provider** step. Supply the three values from Okta. 1. Click **Upload SAML metadata file**. 2. Select the **Identity Provider metadata** XML you downloaded from Okta. StackOne fills in **Entity ID (Issuer)**, **SSO URL (Entry Point)**, and **X.509 Certificate**. 3. Review the imported values before continuing. StackOne Register step with the metadata upload option above the manual entry fields

StackOne Register step with the metadata upload option above the manual entry fields

Set the following: - **Entity ID (Issuer)**: the **Identity Provider Issuer** from Okta. - **SSO URL (Entry Point)**: the **Identity Provider Single Sign-On URL** from Okta. - **X.509 Certificate**: the **X.509 Certificate** from Okta. StackOne Register form completed with the Okta issuer, SSO URL, and certificate

StackOne Register form completed with the Okta issuer, SSO URL, and certificate

Select **Continue**. The connection is registered, but stays inactive until the domain is verified. StackOne SSO connection card showing configuration details and pending domain verification

StackOne SSO connection card showing configuration details and pending domain verification

## Verify the domain Verification proves the organization owns the domain and activates SSO. Once it's verified, existing StackOne users on the domain are linked to the SSO connection, so they keep one account. On the wizard's **Verify your domain** step, copy the record's **Name** and **Value**. The **Value** has this form: ``` _stackone-sso-verification-token-{providerId}={token} ``` StackOne's Verify your domain step showing the DNS TXT record name and value.

StackOne's Verify your domain step showing the DNS TXT record name and value.

In the domain's DNS panel, add a TXT record: - **Name/Host**: the domain. Use `@` if it's the root of the DNS zone, or the subdomain label if the email domain is a subdomain. - **Value**: the full `_stackone-sso-verification-token-...` string, as its own value. Don't append it to an existing TXT value, such as an SPF record. Add the `_stackone-sso-verification-token-...` string as the record's **Value**, not its Name. It looks like a DNS host label, as `_dmarc` and `_domainkey` do, so it's easy to paste into **Name/Host** by mistake. A record on the wrong name fails verification without an error. 1. Go to **DNS > Records** and select **Add record**. 2. Set **Type** to `TXT` and **Name** to `@` for the root domain, or the subdomain label, such as `eu` for `eu.acme.com`. 3. Paste the token into **Content**. Cloudflare allows several TXT records at the same name, so add a new record rather than editing an existing one. 1. Open the hosted zone and select **Create record**. 2. Set **Record type** to `TXT`. Leave **Record name** blank for the root domain, or enter the subdomain label, such as `eu` for `eu.acme.com`. 3. Paste the token in quotes. If a TXT record already exists at that name, edit it and add the token as a new line instead. 1. Open the zone and add a standard record set. 2. Set the type to `TXT`, with the DNS name set to the email domain, such as `acme.com` or `eu.acme.com`. 3. Paste the token. If a TXT record set already exists, edit it and add the token as a new item instead. 1. Open the domain's DNS records and select **Add New Record**. 2. Set **Type** to `TXT` and **Name** to `@` for the root domain, or the subdomain label, such as `eu` for `eu.acme.com`. 3. Paste the token into **Value**. 1. Open **Advanced DNS** and select **Add New Record**. 2. Choose **TXT Record**, and set **Host** to `@` for the root domain, or the subdomain label, such as `eu` for `eu.acme.com`. 3. Paste the token into **Value**. DNS changes can take up to 48 hours to propagate, though they often complete within minutes. Check what's publicly visible with [Google Admin Toolbox Dig](https://toolbox.googleapps.com/apps/dig/#TXT/). 1. Select **Verify**. Once the record is visible, the domain is verified and SSO is active. 2. Select **Finish** to close the wizard. If the check fails, wait for DNS to propagate and try again. To finish setup first, select **Verify Later**, then verify afterward from the **Trusted Domain** card on the connection's **General** tab. StackOne SSO connection card showing the domain as verified and SSO active

StackOne SSO connection card showing the domain as verified and SSO active

## Manage the connection Open the connection from [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). The **General** tab is where you maintain it after setup: - Select **Edit SAML** to update the identity provider values, either by uploading new metadata XML or by editing the **Entity ID (Issuer)**, **SSO URL (Entry Point)**, and **X.509 Certificate** directly. - Select **Edit Domain** to change the trusted domain. Changing it resets verification, so users stop being redirected until you verify it again. You can't change it while SSO is enforced. The connection's General tab, showing the SAML 2.0 Configuration values (Single sign-on URL, Audience URI, Default Relay State) and the Trusted Domain verification status.

The connection's General tab, showing the SAML 2.0 Configuration values (Single sign-on URL, Audience URI, Default Relay State) and the Trusted Domain verification status.

From the connection's page header: - **Settings** edits the **Connection name**. The **Provider ID** is generated at setup and can't be changed. - **Delete** removes the SSO connection. It's disabled while SSO is enforced, so turn off enforcement on the **Authentication** tab first. To require users to sign in through Okta, see [Require SSO](/secure/identity-and-access/authentication/sso/overview#require-sso). Deleting the connection sends users on the domain back to email and password sign-in, so make sure they have another way in first. To change SAML values, use **Edit SAML** instead. Deleting it also removes SCIM Provisioning, if linked, and revokes its token. Provisioning from Okta then fails with `401` until you link SCIM again and paste the new token into Okta. Users already provisioned keep their access. To add, update and deactivate users automatically from Okta, set up [Okta SCIM Provisioning](/secure/identity-and-access/manage-team/scim/okta) once the domain is verified. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | `ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA` | The registered certificate doesn't match the one Okta signs with. Okta issues a new certificate per app. | Re-copy the **X.509 Certificate** from this app's **View SAML setup instructions** and update it via **Edit SAML**. | | `ERR_UNMATCH_ISSUER` | The **Entity ID (Issuer)** doesn't match the issuer Okta sends. | Copy the **Identity Provider Issuer** (`http://www.okta.com/exk...`) and update it via **Edit SAML**. | | "Provider domain has not been verified" | Domain verification hasn't completed. | Finish [Verify the domain](#verify-the-domain). | | Sign-in redirects to the wrong Okta, or a domain appears already taken | StackOne doesn't automatically reserve a domain to one organization, so another StackOne organization may have registered the same domain. | Contact StackOne support to resolve which organization should own SSO for the domain before you enforce it. | | Verification keeps failing | The TXT record is on the wrong name, not its own value, or DNS hasn't propagated. | Use `@` for a root domain or the subdomain label otherwise, add the token as its own TXT value, and check propagation with [Dig](https://toolbox.googleapps.com/apps/dig/#TXT/). | | Users not redirected to Okta | The domain isn't verified, or the user isn't assigned in Okta. | Verify the domain, and confirm the user is on the app's **Assignments** tab. | | New users show their email address as their name | The app sends no name attribute statements, so the assertion carries only the email subject. | Add the `givenName` / `surname` attribute statements to the Okta app (see the setup steps above). | | `403 Forbidden` when opening SSO | You lack the **Organization Admin** role. | Ask an **Organization Admin** to make the change or to grant you the role. | ## Next steps How SSO, domain verification, and SCIM Provisioning fit together. Set up SAML SSO with Entra ID instead of Okta. Connect any SAML 2.0 identity provider. # Microsoft Entra SSO Source: https://docs.stackone.com/secure/identity-and-access/authentication/sso/microsoft-entra Set up SAML Single Sign-On between Microsoft Entra ID and StackOne. SAML SSO is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Connect Microsoft Entra ID (formerly Azure AD) as the organization's SAML 2.0 identity provider (IdP), so users sign in to StackOne with their Entra credentials. Before setting up Microsoft Entra SSO, you need: - The **Organization Admin** role in StackOne. - Access to the **Microsoft Entra admin center** with permission to create enterprise applications, such as the **Application Administrator** or **Cloud Application Administrator** role. - The ability to add a DNS TXT record for your email domain, which proves you own it. ## Start the connection in StackOne 1. Go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Click **Get started**. 3. Select **Microsoft Entra ID** as the provider. On the **Connection details** step, fill in both fields, then select **Continue**: - **Connection name**: a name for the connection. StackOne generates the connection's unique ID from it. - **Domain**: the email domain your users sign in with. The **Configure your identity provider** step has the values you need when you create the app in Entra: - **Reply URL (ACS URL)**: where Entra posts the SAML assertion. - **Identifier (Entity ID)**: identifies StackOne to Entra. - **Default RelayState**: the dashboard URL, where an Entra-initiated sign-in lands. Keep this StackOne tab open. You return to the wizard to register the provider after you build the Entra app. StackOne SSO wizard showing the Reply URL and Identifier values to copy into Microsoft Entra.

StackOne SSO wizard showing the Reply URL and Identifier values to copy into Microsoft Entra.

## Create the SAML app in Microsoft Entra 1. In the **Microsoft Entra admin center**, go to **Identity > Applications > Enterprise applications**. 2. Select **New application > Create your own application**. 3. Enter a name, for example `StackOne SSO`. 4. Choose **Integrate any other application you don't find in the gallery (Non-gallery)**, then select **Create**. 1. Open the new application and go to **Single sign-on**. 2. Select **SAML**. 1. In **Basic SAML Configuration**, select **Edit**. 2. Set the following: - **Identifier (Entity ID)**: the **Identifier (Entity ID)** from StackOne. - **Reply URL (Assertion Consumer Service URL)**: the **Reply URL (ACS URL)** from StackOne. - **Relay State (Optional)**: the **Default RelayState** from StackOne. 3. Select **Save**. Microsoft Entra, Basic SAML Configuration, with Identifier (Entity ID) and Reply URL (ACS URL) set to the StackOne values.

Microsoft Entra, Basic SAML Configuration, with Identifier (Entity ID) and Reply URL (ACS URL) set to the StackOne values.

1. In **Attributes & Claims**, select **Edit**. 2. Open **Unique User Identifier (Name ID)**. 3. Set the following: - **Name identifier format**: `Email address`. - **Source attribute**: `user.mail`. 4. Save the claim. Microsoft Entra, Attributes & Claims, with the unique user identifier (Name ID) source set to user.mail and format Email address.

Microsoft Entra, Attributes & Claims, with the unique user identifier (Name ID) source set to user.mail and format Email address.

`user.mail` must be set for everyone who signs in. It's often empty for cloud-only accounts without an Exchange Online mailbox, and for users synced from on-premises Active Directory without a `mail` attribute. When it's empty, sign-in fails with "Unable to extract user ID or email from SAML response". If users' UPN matches their email address, use `user.userprincipalname` as the source attribute instead. Otherwise, set `mail` for each user before they sign in. 1. In **Attributes & Claims**, select **Add new claim**. 2. Set **Name** to `givenName`, leave **Namespace** blank, and set **Source attribute** to `user.givenname`. Select **Save**. 3. Repeat with **Name** set to `surname` and **Source attribute** set to `user.surname`. These set the user's display name in StackOne. Adding these to an existing app only sets names for new users. To sync names for existing users, use [SCIM Provisioning](/secure/identity-and-access/manage-team/scim/microsoft-entra). 1. Go to **Users and groups** and select **Add user/group**. 2. Assign the people or groups who should sign in to StackOne through Entra. Only assigned users can complete SSO. On the **Single sign-on** page, get the values StackOne needs. In **SAML Certificates**, download the **Federation Metadata XML**. 1. From **Set up [App name]**, copy the **Login URL** and the **Microsoft Entra Identifier**. 2. In **SAML Certificates**, download the **Certificate (Base64)**. Microsoft Entra, SAML Certificates, where you download the Federation Metadata XML or the Base64 certificate.

Microsoft Entra, SAML Certificates, where you download the Federation Metadata XML or the Base64 certificate.

## Register the provider in StackOne Switch back to the StackOne tab and continue to the **Register your SSO provider** step. Supply the three values from Entra. 1. Select **Upload SAML metadata file**. 2. Select the **Federation Metadata XML** you downloaded. StackOne fills in **Entity ID (Issuer)**, **SSO URL (Entry Point)**, and **X.509 Certificate**. 3. Review the imported values before continuing. StackOne register step with fields for the issuer, SSO URL, and certificate, plus the metadata upload button.

StackOne register step with fields for the issuer, SSO URL, and certificate, plus the metadata upload button.

Set the following: - **Entity ID (Issuer)**: the **Microsoft Entra Identifier**. - **SSO URL (Entry Point)**: the **Login URL**. - **X.509 Certificate**: the contents of the **Certificate (Base64)** file. StackOne SSO registration form filled with the Microsoft Entra values before registering.

StackOne SSO registration form filled with the Microsoft Entra values before registering.

Select **Continue**. The connection is registered, but stays inactive until the domain is verified. ## Verify the domain Verification proves the organization owns the domain and activates SSO. Once it's verified, existing StackOne users on the domain are linked to the SSO connection, so they keep one account. On the wizard's **Verify your domain** step, copy the record's **Name** and **Value**. The **Value** has this form: ``` _stackone-sso-verification-token-{providerId}={token} ``` StackOne's Verify your domain step showing the DNS TXT record name and value.

From the connection's page header: - **Settings** edits the **Connection name**. The **Provider ID** is generated at setup and can't be changed. - **Delete** removes the SSO connection. It's disabled while SSO is enforced, so turn off enforcement on the **Authentication** tab first. To require users to sign in through Microsoft Entra, see [Require SSO](/secure/identity-and-access/authentication/sso/overview#require-sso). Deleting the connection sends users on the domain back to email and password sign-in, so make sure they have another way in first. To change SAML values, use **Edit SAML** instead. Deleting it also removes SCIM Provisioning, if linked, and revokes its token. Provisioning from Microsoft Entra then fails with `401` until you link SCIM again and paste the new token into Microsoft Entra. Users already provisioned keep their access. To add, update and deactivate users automatically from Microsoft Entra, set up [Microsoft Entra SCIM Provisioning](/secure/identity-and-access/manage-team/scim/microsoft-entra) once the domain is verified. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | Sign-in fails with "Unable to extract user ID or email" | The Name ID is empty because `user.mail` isn't set for that user. | Populate `user.mail`, or set the Name ID source to `user.userprincipalname` if it matches the user's email. | | `ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA` | The registered certificate doesn't match the one Entra signs with, usually after Entra rotated or renewed it. | Download a fresh **Federation Metadata XML** (or **Certificate (Base64)**) from **SAML Certificates** and update it via **Edit SAML**. Entra signing certificates expire on a schedule, roughly every three years. | | `ERR_UNMATCH_ISSUER` | The **Entity ID (Issuer)** doesn't match the issuer Entra sends. | Copy the **Microsoft Entra Identifier** and update it via **Edit SAML**. | | "Provider domain has not been verified" | Domain verification hasn't completed. | Finish [Verify the domain](#verify-the-domain). | | Verification keeps failing | The TXT record is on the wrong name, not its own value, or DNS hasn't propagated. | Use `@` for a root domain or the subdomain label otherwise, add the token as its own TXT value, and check propagation with [Dig](https://toolbox.googleapps.com/apps/dig/#TXT/). | | Users not redirected to Entra | The domain isn't verified, or the user isn't assigned in Entra. | Verify the domain, and confirm the user is under **Users and groups** on the enterprise application. | | `403 Forbidden` when opening SSO | You lack the **Organization Admin** role. | Ask an **Organization Admin** to make the change or to grant you the role. | ## Next steps See how SSO, domain verification, and SCIM Provisioning fit together. Set up the same SAML connection with Okta instead of Entra. Connect any other identity provider that supports SAML 2.0. # Generic SAML SSO Source: https://docs.stackone.com/secure/identity-and-access/authentication/sso/saml-generic Set up SAML Single Sign-On with any SAML 2.0 identity provider. SAML SSO is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Connect any SAML 2.0 identity provider (IdP) to StackOne, so users sign in with their IdP credentials. If the IdP is Okta or Microsoft Entra ID, follow the [Okta](/secure/identity-and-access/authentication/sso/okta) or [Microsoft Entra](/secure/identity-and-access/authentication/sso/microsoft-entra) guide instead. Before setting up SAML SSO, you need: - The **Organization Admin** role in StackOne. - Admin access to the IdP, to create and configure a SAML application. - The ability to add a DNS TXT record for your email domain, which proves you own it. ## Start the connection in StackOne 1. Go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Click **Get started**. 3. Select **Other SAML 2.0 provider**, then click **Continue**. On the **Connection details** step, fill in both fields, then click **Continue**: - **Connection name**: a name for the connection. StackOne generates the connection's unique ID from it. - **Domain**: the email domain your users sign in with. The **Configure your identity provider** step has the values you need when you create the app in your IdP. Field names vary by IdP: - **ACS URL (Single sign-on URL)**: where the IdP posts the SAML assertion. Often called Assertion Consumer Service URL or Reply URL. - **SP Entity ID (Audience)**: identifies StackOne to the IdP. Often called Audience URI, Entity ID or Identifier. - **Default RelayState**: the dashboard URL, where an IdP-initiated sign-in lands. Set it only if the IdP supports IdP-initiated sign-in. Keep this StackOne tab open. You return to the wizard to register the provider after you build the app in your IdP. The Configure your identity provider step showing the ACS URL, SP Entity ID, and Default RelayState

The Configure your identity provider step showing the ACS URL, SP Entity ID, and Default RelayState

## Create the SAML app in your IdP 1. In the IdP's admin console, create a new SAML 2.0 application for StackOne. 2. Set the following: - **Single sign-on URL** (or Assertion Consumer Service URL): the **ACS URL** from StackOne. - **Audience URI** (or Entity ID): the **SP Entity ID** from StackOne. - **Relay State** (optional): the **Default RelayState** from StackOne. Set the following: - **Name ID format**: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. - **Name ID value**: the user's work email, not a username, UPN or object ID. Optionally, also send the email as an attribute named `email`. StackOne uses it when present, and falls back to the Name ID otherwise. Add attributes named `givenName` and `surname`, or a single `displayName`. These set the user's display name in StackOne. Adding these to an existing app only sets names for new users. To sync names for existing users, use [SCIM Provisioning](/secure/identity-and-access/manage-team/scim/overview). Enable assertion signing in the IdP. StackOne validates the signature against the certificate you register in StackOne. Register the exact certificate the IdP signs with. A mismatch makes every sign-in fail with a certificate error, even when every other value is correct. Assign the users or groups who should sign in to StackOne through this application, then save the app. Only assigned users can complete SSO. From the IdP's SAML settings, get the values StackOne needs. Download the IdP's SAML metadata XML. Copy these values for StackOne: - **Issuer (Entity ID)**: the IdP's unique identifier. - **Single Sign-On URL**: the IdP's login endpoint. - **X.509 signing certificate**: in PEM format. ## Register the provider in StackOne Switch back to the StackOne tab and continue to the **Register your SSO provider** step. Supply the three values from the IdP. 1. Click **Upload SAML metadata file**. 2. Select the metadata XML you downloaded. StackOne fills in **Entity ID (Issuer)**, **SSO URL (Entry Point)**, and **X.509 Certificate**. 3. Review the imported values before continuing. Set the following: - **Entity ID (Issuer)**: the IdP's **Issuer (Entity ID)**. - **SSO URL (Entry Point)**: the IdP's **Single Sign-On URL**. - **X.509 Certificate**: the IdP's **X.509 signing certificate**. The Register your SSO provider step with the Entity ID, SSO URL, and X.509 Certificate fields

The Register your SSO provider step with the Entity ID, SSO URL, and X.509 Certificate fields

From the connection's page header: - **Settings** edits the **Connection name**. The **Provider ID** is generated at setup and can't be changed. - **Delete** removes the SSO connection. It's disabled while SSO is enforced, so turn off enforcement on the **Authentication** tab first. To require users to sign in through your IdP, see [Require SSO](/secure/identity-and-access/authentication/sso/overview#require-sso). Deleting the connection sends users on the domain back to email and password sign-in, so make sure they have another way in first. To change SAML values, use **Edit SAML** instead. Deleting it also removes SCIM Provisioning, if linked, and revokes its token. Provisioning from your IdP then fails with `401` until you link SCIM again and paste the new token into your IdP. Users already provisioned keep their access. To add, update and deactivate users automatically from your IdP, set up [SCIM Provisioning](/secure/identity-and-access/manage-team/scim/overview) once the domain is verified. ## Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| | `403 Forbidden` when opening SSO | You lack the **Organization Admin** role. | Ask an **Organization Admin** to make the change or to grant you the role. | | `ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA` | The registered certificate doesn't match the one the IdP signs with. | Re-copy the active **X.509 signing certificate** from the IdP and update it on the connection's **General** tab via **Edit SAML**. | | `ERR_UNMATCH_ISSUER` | The **Entity ID (Issuer)** doesn't match the issuer the IdP sends. | Copy the issuer from the IdP's SAML metadata and update it via **Edit SAML**. | | Sign-in fails or signs in the wrong user | The Name ID value isn't the user's email, the format is set to email address, but the value is still a username, UPN, or object ID. | Set the Name ID value to the user's work email (see [Set the Name ID to the user's email](#create-the-saml-app-in-your-idp)). | | "Provider domain has not been verified" | Domain verification hasn't completed. | Finish [Verify the domain](#verify-the-domain). | | Domain verification keeps failing | The TXT record is on the wrong name, was appended to an existing value, or DNS hasn't propagated. | Use `@` for a root domain or the subdomain label otherwise, add the token as its own TXT value, and check propagation with [Dig](https://toolbox.googleapps.com/apps/dig/#TXT/). | | Users not redirected to the IdP | The domain isn't verified, or the user isn't assigned to the SAML application. | Verify the domain, and confirm the user is assigned in the IdP. | ## Next steps How SSO, SCIM Provisioning, and domain verification fit together. The same setup with Okta's field names and screenshots. The same setup with Microsoft Entra ID. # Passwords and MFA Source: https://docs.stackone.com/secure/identity-and-access/authentication/passwords-and-mfa Change your password, turn on multi-factor authentication, and enforce it for the organization. Users change their own password and turn on MFA from their account settings. **Organization Admins** can also enforce MFA for everyone in the organization. ## Change your password Open your [account settings](https://app.stackone.com/account/security). You can also click your name in the bottom-left corner of the dashboard, then open **Account** settings. 1. Click **Change Password**. 2. Enter your **Current Password**. 3. Enter your new password in both **New Password** and **Confirm New Password**. 4. Click **Change Password**. ## Turn on MFA for your account Open your [account settings](https://app.stackone.com/account/security). You can also click your name in the bottom-left corner of the dashboard, then open **Account** settings. Click **Enable Multi-Factor Authentication**. Scan the QR code with your authenticator app, such as Google Authenticator, Microsoft Authenticator, or 1Password. MFA setup dialog with QR code, authentication secret, and code confirmation

MFA setup dialog with QR code, authentication secret, and code confirmation

Enter the 6-digit code from your authenticator app to confirm. ## Enforce MFA for the organization **Organization Admins** can require multi-factor authentication (MFA) for everyone in the organization, current and future users alike. 1. Go to [**Organization > Security > Authentication**](https://app.stackone.com/organization/security/authentication). 2. On the **Multi-factor Authentication** card, select **Enable MFA**. 3. Select **Confirm**. Users without MFA set it up the next time they sign in. ## Help a user who is locked out An **Organization Admin** can unlock an account locked by failed sign-ins, or reset another user's MFA. Select **Unlock User** or **Reset MFA** from the user's menu on the **Users** tab of [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team). # Manage Team Source: https://docs.stackone.com/secure/identity-and-access/manage-team/overview Bring people into the organization, and make sure they lose access when they leave. [**Organization Admins**](/secure/identity-and-access/roles-and-groups/organization-roles) manage who can access the StackOne organization. Manage everyone in the organization, from the day they join to the day they leave. Users join in one of three ways: An **Organization Admin** sends an email invite and picks the user's role. Users join when they sign in with SSO and aren't a member yet. The identity provider adds and removes users as the directory changes. ## Using multiple provisioning methods An organization can use more than one of these at once. When multiple methods are used, user management can be taken over by the identity provider (IdP): | User's current status | Email invitation | Just-in-Time Provisioning | SCIM Provisioning | | --- | --- | --- | --- | | **Already a member** | Can't be sent to an existing member. | Leaves them as they are. | Starts managing them when the IdP assigns them. | | **Invited, but hasn't accepted yet** | Adds them with the invitation's role when they accept it. | Doesn't add them. They join only by accepting the invitation. | Adds them with the role the IdP sends, not the invitation's. The invitation should be removed. | | **Neither** | Adds them when they accept it. | Adds them the first time they sign in to StackOne with SSO. | Adds them when the IdP assigns them. | ## Removing access to the organization Disabling or deleting a user ends their access to the organization, including any [AI platform](/connect/ai-platforms/overview) connections they made to it. - **Disable** keeps their roles, group memberships and seat, so enabling them again restores their access. - **Delete** removes their roles and group memberships, and frees their seat. To give them access again, invite them back. An organization's last active **Organization Admin** cannot be disabled or deleted. How to remove someone depends on how the organization adds people: | The organization uses | Remove them by | |---|---| | Invitations only | Disabling or deleting them on the **Users** tab of [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team). | | Just-in-Time Provisioning | Following the steps in [Just-in-Time Provisioning > Remove access to the organization](/secure/identity-and-access/manage-team/jit#remove-access-to-the-organization). | | SCIM Provisioning | Following the steps in [SCIM Provisioning > Deprovisioning](/secure/identity-and-access/manage-team/scim/overview#deprovisioning). | # Invite Users Source: https://docs.stackone.com/secure/identity-and-access/manage-team/invite-users Add people to the organization by email, and choose their organization and project roles. Only **Organization Admins** can invite users. In the StackOne dashboard, go to [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team). Organization > Manage Team, showing the Users tab with each user's role, and the invites tab

Organization > Manage Team, showing the Users tab with each user's role, and the invites tab

Click **Invite User** and enter the person's email address. To invite several people at once, separate their addresses with commas. 1. Pick their organization **Role**: **Organization Admin** or **Organization Member**. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). 2. Optionally, select the **Projects** to add them to, and their **Project Role**. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). You can also add them to projects later, from **Project Settings > Access**. Click **Confirm**. Pending invites wait on the **Invites** tab, where you can resend or remove them. # Just-in-Time Provisioning Source: https://docs.stackone.com/secure/identity-and-access/manage-team/jit Add users to the organization automatically the first time they sign in with SSO. SAML SSO is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). **Just-in-Time (JIT) Provisioning** adds users from your identity provider (IdP) to the organization the first time they sign in with SSO. There's no invitation to send and no directory to sync. ## Set up JIT Before setting up JIT, you need: - A verified SSO connection between the organization and your IdP. See [Single Sign-On](/secure/identity-and-access/authentication/sso/overview). - The **Organization Admin** role in StackOne. - (Optional) The IdP set up to send the `stackone_role` attribute with the value `admin` for anyone who should join as an **Organization Admin**. Everyone else joins as an **Organization Member**. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). The IdP's value only counts when a user first joins. After that, their role can only be changed in StackOne. 1. In the StackOne dashboard, go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Open the verified SSO connection. 3. Select the **Provisioning** tab. 1. On the **Provisioned access** card, select **Manage access**. 2. Pick the projects new users should join. 3. Choose a role for each one. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). 4. Select **Save changes**. Provisioned access applies to users added by both Just-in-Time Provisioning and SCIM Provisioning. The Provisioned access panel with a project checked and its own role dropdown set to Viewer, and a note that the organization role is set separately.

The Provisioned access panel with a project checked and its own role dropdown set to Viewer, and a note that the organization role is set separately.

On the **Just-in-time provisioning** card, select **Enable JIT**. Assign the users to the StackOne application in the IdP. Each one joins the organization the first time they sign in with SSO, with the provisioned access you chose. **Provisioned access** only applies when a user first joins, so JIT doesn't give back access you removed from an existing member. ## When a user isn't added A user can sign in with SSO and still not be added to the organization if: - Their email address isn't on the connection's verified domain. The match is exact, so `@eu.acme.com` doesn't count for `acme.com`. - The organization has no seats left. - The organization's required sign-in methods don't include SSO. - They have a pending invitation. They join when they accept it instead. See [Using multiple provisioning methods](/secure/identity-and-access/manage-team/overview#using-multiple-provisioning-methods). ## Remove access to the organization To stop a user accessing the organization: 1. Go to [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team). 2. On the **Users** tab, find the user. 3. Select **Disable User**. Their membership still exists, so JIT can't create a new one when they sign in. You can also unassign them from the StackOne application in the IdP, so they can't sign in with SSO at all. **Deleting a user** in StackOne doesn't keep them out while they can still sign in through the IdP. They rejoin at their next sign-in, as if they were joining for the first time. ## Next steps Grant many users the same project or linked account access at once. Add and remove users from the directory instead of at sign-in. # SCIM Provisioning Source: https://docs.stackone.com/secure/identity-and-access/manage-team/scim/overview Add, update and deactivate users automatically from your identity provider's directory. SCIM Provisioning is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). **SCIM Provisioning** creates and deactivates StackOne members automatically from your identity provider (IdP). It can also [sync the IdP's groups](/secure/identity-and-access/manage-team/scim/groups) into StackOne, where they can grant access to projects and linked accounts. Flow diagram with three lanes from an identity provider such as Okta or Microsoft Entra into StackOne. Assign a user: they join the organization and get their role and provisioned access. Push a group: it becomes a StackOne group you assign to projects and accounts. Deactivate or remove a user: their access is suspended, and they are removed from synced groups and signed out.

Flow diagram with three lanes from an identity provider such as Okta or Microsoft Entra into StackOne. Assign a user: they join the organization and get their role and provisioned access. Push a group: it becomes a StackOne group you assign to projects and accounts. Deactivate or remove a user: their access is suspended, and they are removed from synced groups and signed out.

## Enable SCIM Provisioning To set up SCIM Provisioning with Okta or Microsoft Entra, follow the [Okta](/secure/identity-and-access/manage-team/scim/okta) or [Microsoft Entra](/secure/identity-and-access/manage-team/scim/microsoft-entra) guide instead. Google Workspace doesn't support SCIM Provisioning. Before setting up SCIM Provisioning, you need: - A verified SSO connection between the organization and your IdP. See [Single Sign-On](/secure/identity-and-access/authentication/sso/overview). - The **Organization Admin** role in StackOne. - Admin access to the StackOne application in your IdP. - (Optional) your IdP set up to send `admin` in the SCIM `roles` field for anyone who should join as an **Organization Admin**. Everyone else joins as an **Organization Member**. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). The `roles` value only counts when a user first joins. After that, their role can only be changed in StackOne. SCIM Provisioning only adds users whose email is on the organization's verified domain. Anyone else, including everyone assigned before the domain is verified, shows as an error in your IdP's provisioning log. 1. In the StackOne dashboard, go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Open the verified SSO connection. 3. Select the **Provisioning** tab. 1. On the **Provisioned access** card, select **Manage access**. 2. Pick the projects new users should join. 3. Choose a role for each one. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). 4. Select **Save changes**. Provisioned access applies to users added by both Just-in-Time Provisioning and SCIM Provisioning. The Provisioned access panel with a project checked and its own role dropdown set to Viewer, and a note that the organization role is set separately.

1. On the **Directory Sync** card, select **Link SCIM**. 2. In the **SCIM Details** section, copy the **SCIM base URL** and the **Provisioning token**. You paste both into the IdP. The Provisioning tab on an SSO connection, showing the Provisioned access, Just-in-time provisioning, and Directory Sync cards with their Manage access, Enable JIT, and Link SCIM actions.

The Provisioning tab on an SSO connection, showing the Provisioned access, Just-in-time provisioning, and Directory Sync cards with their Manage access, Enable JIT, and Link SCIM actions.

The Directory Sync panel showing the SCIM base URL and the masked provisioning token with a Regenerate action.

The token is only shown once. Store it somewhere safe before you close the panel. To replace a lost or leaked token, see [Rotate the token](/secure/identity-and-access/manage-team/scim/overview#rotate-the-token). In the IdP, enable provisioning for the StackOne application, paste in the SCIM base URL and token, and assign the users who should sync. ## When a user is assigned When you assign a user to the StackOne application in the IdP: - The user is added to the organization. - The user gets the connection's **provisioned access**. It's applied again on every update from the IdP, so a project you remove from the user in StackOne comes back. - The user joins any [synced groups](/secure/identity-and-access/manage-team/scim/groups) the IdP pushes them into, and gets the access those groups grant. ## Deprovisioning Deprovisioning affects every user the IdP manages through SCIM Provisioning, including people who first joined by invitation or Just-in-Time Provisioning. Users the IdP has never assigned are left untouched. When you deactivate or remove a user in the IdP: - The user's access to the organization is suspended. - The user is removed from their synced groups. - The user is signed out on any device where they're currently working in the organization. Reactivating the user in the IdP lifts the suspension, unless an **Organization Admin** also disabled them in StackOne. SCIM Provisioning never deactivates the organization's last active **Organization Admin**. To offboard them, first make someone else an **Organization Admin**. Until then, the IdP's provisioning log shows the deactivation as an error, and it retries on each sync. **Deleting a user** in StackOne doesn't remove them while the IdP still assigns them. The next sync adds them back, so deactivate or remove them in the IdP instead. ## Manage or remove SCIM Provisioning Manage SCIM Provisioning from the **Directory Sync** card on the SSO connection's **Provisioning** tab. ### Rotate the token 1. Select **Edit SCIM**. 2. Select **Regenerate**, then **Confirm rotate**. 3. Paste the new token into the IdP. The old token stops working immediately, so SCIM Provisioning fails until the IdP has the new one. ### Change provisioned access Select **Manage access** on the **Provisioned access** card. New users get the updated access. Users SCIM Provisioning already manages get any added projects on their next update from the IdP, but keep projects you removed and their role on projects they already had. Synced groups grant access separately. When a user has a project through both, the strongest role applies. See [Which role applies](/secure/identity-and-access/roles-and-groups/overview#which-role-applies). ### Unlink SCIM Provisioning Select **Unlink**. This stops all future provisioning and revokes the token. Users synced so far keep their access, and synced groups become normal groups that keep their members and assignments. If you link again later, the SCIM base URL stays the same, so you only paste the new token into the IdP. Deleting the SSO connection unlinks SCIM Provisioning in the same way. If you delete and recreate the connection, for example to replace a certificate, link SCIM again and paste the new token into the IdP. ## Next steps Enable SCIM provisioning on an Okta SSO connection. Enable SCIM provisioning on a Microsoft Entra SSO connection. Set up the SSO connection that SCIM Provisioning builds on. Push the IdP's groups into StackOne and grant access through them. # Okta SCIM Provisioning Source: https://docs.stackone.com/secure/identity-and-access/manage-team/scim/okta Connect Okta to StackOne with SCIM, assign users, and push Okta groups. SCIM Provisioning is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Sync users from Okta, your identity provider (IdP), into StackOne with SCIM. Once linked, assigning a person to the StackOne app in Okta adds them to the organization, and unassigning or deactivating them removes their access. For what happens to users once SCIM Provisioning is running, see the [SCIM Provisioning overview](/secure/identity-and-access/manage-team/scim/overview). Before setting up SCIM Provisioning, you need: - A verified SSO connection between the organization and Okta. See [Single Sign-On](/secure/identity-and-access/authentication/sso/overview). - The **Organization Admin** role in StackOne. - Admin access to the StackOne application in Okta. - (Optional) Okta set up to send `admin` in the SCIM `roles` field for anyone who should join as an **Organization Admin**. Everyone else joins as an **Organization Member**. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). The `roles` value only counts when a user first joins. After that, their role can only be changed in StackOne. SCIM Provisioning only adds users whose email is on the organization's verified domain. Anyone else, including everyone assigned before the domain is verified, shows as an error in Okta's provisioning log. ## Link SCIM in StackOne 1. In the StackOne dashboard, go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Open the verified SSO connection. 3. Select the **Provisioning** tab. 1. On the **Provisioned access** card, select **Manage access**. 2. Pick the projects new users should join. 3. Choose a role for each one. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). 4. Select **Save changes**. Provisioned access applies to users added by both Just-in-Time Provisioning and SCIM Provisioning. The Provisioned access panel with a project checked and its own role dropdown set to Viewer, and a note that the organization role is set separately.

The token is only shown once. Store it somewhere safe before you close the panel. To replace a lost or leaked token, see [Rotate the token](/secure/identity-and-access/manage-team/scim/overview#rotate-the-token). ## Configure provisioning in Okta 1. In the Okta admin console, go to **Applications > Applications** and open the app you created for StackOne SSO. 2. Go to the **Provisioning** tab. 3. Click **Configure API Integration**. 4. Select **Enable API integration**. 1. Set the following: - **SCIM connector base URL**: the **SCIM base URL** from StackOne. - **Unique identifier field for users**: `userName`. - **Supported provisioning actions**: `Push New Users` and `Push Profile Updates`. - **Authentication Mode**: `HTTP Header`. - **Authorization**: the **Provisioning token** from StackOne. 2. Click **Test Connector Configuration** to confirm Okta can reach StackOne. 3. Click **Save**. Okta, Provisioning > Integration, showing the SCIM Connection with the connector base URL, userName as the unique identifier, Push New Users and Push Profile Updates enabled, and HTTP Header bearer-token authentication.

1. Under **Provisioning > To App**, click **Edit**. 2. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. 3. Click **Save**. These let Okta create members in StackOne, keep their profiles in sync, and remove access when you unassign or deactivate them. Okta, Provisioning > To App, with Create Users, Update User Attributes, and Deactivate Users all enabled.

Okta, Provisioning > To App, with Create Users, Update User Attributes, and Deactivate Users all enabled.

## Assign members in Okta 1. Open the **Assignments** tab of the StackOne app. 2. Assign the people you want in StackOne. You can assign individuals or Okta groups. Either way, Okta adds each assigned person to the organization, with their organization role and provisioned access. Assigning an Okta group provisions its members as individual users. To bring the group itself into StackOne, with its membership kept in step, push it as well. See [Push groups](#push-groups). Return to the **Directory Sync** card in StackOne. The **Synced members** and **Last synced** values update as Okta pushes users, and new members appear in the projects you selected. ## Push groups Okta's **Group Push** creates the group in StackOne as a synced group and keeps its members in step. Only members who are assigned to the StackOne app, and so already provisioned, are pushed. If StackOne already has a group with the same name, an empty one becomes the synced group and keeps its access. If the group has members, it's left untouched, and StackOne creates a second, synced group with the same name instead. To set up a group's access before anyone is pushed into it, see [Prepare the access before you push](/secure/identity-and-access/manage-team/scim/groups#prepare-the-access-before-you-push). 1. On the app's **Provisioning** tab, under **Integration**, click **Edit**. 2. Make sure **Push Groups** is enabled alongside **Push New Users** and **Push Profile Updates**. 3. Click **Save**. 1. Open the app's **Push Groups** tab. 2. Click **Push Groups**, and choose **Find groups by name**. To push several groups that share a naming pattern, choose **Find groups by rule** instead. 3. Select the Okta group, and leave **Push group memberships immediately** on. 4. Click **Save**. Okta creates the group in StackOne. 1. Go to [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team) and open the **Groups** tab. The group is listed with a **Synced** tag and its pushed members. 2. Assign it to projects from its **Projects** tab. Use different Okta groups for assigning the app and for Group Push. For example, assign the app to ***StackOne Users*** and push ***Finance***. Okta doesn't support using one group for both, and the group's members in StackOne can end up different from Okta's. See Okta's [App assignments and Group Push](https://help.okta.com/en-us/content/topics/users-groups-profiles/app-assignments-group-push.htm). After a group is pushed: - **To rename it**, rename it in Okta. - **To stop pushing it**: 1. On the **Push Groups** tab, choose **Unlink pushed group** on the group's row. 2. Choose whether to also delete the group in StackOne. A group you keep stays a synced group in StackOne until you unlink SCIM Provisioning. ## Next steps How SCIM provisioning works across identity providers. Provision members from Microsoft Entra ID instead. Push the identity provider's groups into StackOne and grant access through them. # Microsoft Entra SCIM Provisioning Source: https://docs.stackone.com/secure/identity-and-access/manage-team/scim/microsoft-entra Connect Microsoft Entra ID to StackOne with SCIM, assign users, and provision Entra groups. SCIM Provisioning is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Sync users from Microsoft Entra ID, your identity provider (IdP), into StackOne with SCIM. Once linked, assigning a person to the StackOne application in Entra adds them to the organization, and unassigning or disabling them removes their access, except for the organization's last active **Organization Admin**. For what happens to users once SCIM Provisioning is running, see the [SCIM Provisioning overview](/secure/identity-and-access/manage-team/scim/overview). Before setting up SCIM Provisioning, you need: - A verified SSO connection between the organization and Microsoft Entra. See [Single Sign-On](/secure/identity-and-access/authentication/sso/overview). - The **Organization Admin** role in StackOne. - Admin access to the StackOne application in Microsoft Entra. - (Optional) Microsoft Entra set up to send `admin` in the SCIM `roles` field for anyone who should join as an **Organization Admin**. Everyone else joins as an **Organization Member**. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). The `roles` value only counts when a user first joins. After that, their role can only be changed in StackOne. SCIM Provisioning only adds users whose email is on the organization's verified domain. Anyone else, including everyone assigned before the domain is verified, shows as an error in Microsoft Entra's provisioning log. In Microsoft Entra, admin access means permission to manage the enterprise application, such as the **Application Administrator** role. ## Link SCIM in StackOne 1. In the StackOne dashboard, go to [**Organization > Security > SSO**](https://app.stackone.com/organization/security/sso). 2. Open the verified SSO connection. 3. Select the **Provisioning** tab. 1. On the **Provisioned access** card, select **Manage access**. 2. Pick the projects new users should join. 3. Choose a role for each one. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). 4. Select **Save changes**. Provisioned access applies to users added by both Just-in-Time Provisioning and SCIM Provisioning. The Provisioned access panel with a project checked and its own role dropdown set to Viewer, and a note that the organization role is set separately.

The token is only shown once. Store it somewhere safe before you close the panel. To replace a lost or leaked token, see [Rotate the token](/secure/identity-and-access/manage-team/scim/overview#rotate-the-token). ## Configure provisioning in Microsoft Entra Point the enterprise application at StackOne's SCIM endpoint. Use the same application you set up for SSO. 1. In the **Microsoft Entra admin center**, go to **Identity > Applications > Enterprise applications** and open the application you created for StackOne SSO. 2. Select **Provisioning**. 3. Select **Connect your application**. Under **Admin credentials**, set the following: - **Select authentication method**: `Bearer authentication`. - **Tenant URL**: the **SCIM base URL** from StackOne. - **Secret token**: the **Provisioning token** from StackOne. Microsoft Entra, Provisioning > Admin credentials, with Bearer authentication selected, the Tenant URL (SCIM base URL) and Secret token (provisioning token) entered, and the Test connection button.

Microsoft Entra, Provisioning > Admin credentials, with Bearer authentication selected, the Tenant URL (SCIM base URL) and Secret token (provisioning token) entered, and the Test connection button.

1. Click **Test connection**. 2. When the test passes, select **Create** to save the configuration. Select **Start provisioning** to begin the first cycle. Microsoft Entra provisions the assigned users, then re-syncs roughly every 40 minutes. Microsoft Entra, the provisioning overview after connecting, with Start provisioning in the toolbar and the current cycle status.

Microsoft Entra, the provisioning overview after connecting, with Start provisioning in the toolbar and the current cycle status.

## Assign users and groups Microsoft Entra provisions only the users you assign to the application. Assign the people who should have StackOne access. 1. In the same enterprise application, open **Users and groups**. 2. Add the users or groups to sync, such as the **Finance** group. On its next cycle, Microsoft Entra adds each assigned user to the organization, with their organization role and provisioned access. Unassign a user from the application, or disable their Microsoft Entra account, and the next cycle deactivates the matching StackOne member, removing their access automatically. ## Provision groups Microsoft Entra can provision the groups you assign to the application as well as their members. Each becomes a synced group in StackOne that keeps its membership in step with Entra. If StackOne already has a group with the same name, an empty one becomes the synced group and keeps its access. If the group has members, it's left untouched, and StackOne creates a second, synced group with the same name instead. To set up a group's access before anyone is provisioned into it, see [Prepare the access before you push](/secure/identity-and-access/manage-team/scim/groups#prepare-the-access-before-you-push). 1. In the application's **Provisioning** settings, open **Mappings**. 2. Make sure **Provision Microsoft Entra ID Groups** is `Enabled`. Under **Users and groups**, assign the group, such as **Finance**. On the next cycle, Entra provisions the group's direct members as StackOne members and the group itself as a synced group. Nested groups aren't expanded, so assign the groups that directly contain the people you want. 1. Go to [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team) and open the **Groups** tab. The group is listed with a **Synced** tag. 2. Assign it to projects from its **Projects** tab. After a group is provisioned: - **To rename it or change its members**, make the change in Entra. The synced group follows on the next cycle. - **To stop provisioning it**, unassign the group from the application. On the next cycle, Entra deprovisions the members who are no longer assigned to the application through any other assignment. ## Next steps How SCIM provisioning works and how it attaches to the SSO connection. Set up SCIM provisioning with Okta instead of Microsoft Entra. Push the identity provider's groups into StackOne and grant access through them. # SCIM Groups Source: https://docs.stackone.com/secure/identity-and-access/manage-team/scim/groups Push groups from the identity provider into StackOne over SCIM and grant access through them. SCIM Provisioning is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). SCIM Provisioning can push the identity provider's groups into StackOne as **synced groups**. The identity provider (IdP) owns each synced group's name and members, and you grant access with it in StackOne like any other group. Add someone to the group in the IdP and they gain the projects the group is assigned to. Remove them and that access goes with them. ## How synced groups work When the IdP pushes a group, StackOne creates a group of the same name on the **Groups** tab of **Organization > Manage Team**, marked with a **Synced** tag. From then on: - **The IdP manages the name and the members.** Rename the group there and it is renamed here. Add or remove members there and the membership follows. In StackOne the group is marked **Managed by the identity provider**, and renaming it, deleting it, and editing its members are disabled. - **You manage its access.** Assign the group to projects and accounts and choose a role, the same way as for any other group. See [Assign Group Access](/secure/identity-and-access/roles-and-groups/groups). - **Its members are people the directory has provisioned.** A synced group can only contain members that SCIM Provisioning created or linked through the same connection. Someone who is in the directory group but not assigned to the StackOne application isn't a StackOne member, so they don't appear in the group until they are. Synced groups never change anyone's organization role. See [Organization Roles](/secure/identity-and-access/roles-and-groups/organization-roles). ## Prerequisites - **SCIM Provisioning linked** on the SSO connection, with users provisioning. See [Enable SCIM Provisioning](/secure/identity-and-access/manage-team/scim/overview#enable-scim-provisioning). - [Groups](/secure/identity-and-access/roles-and-groups/groups) available in the organization. - Organization **Admin**, or **Admin** on the project, to assign a group to a project. ## Prepare the access before you push A pushed group takes over an existing StackOne group of the same name when that group has no members. Names match ignoring case and surrounding spaces. This lets you set up the access before anyone arrives: 1. On the **Groups** tab, click **Create group**. 2. Give it the exact name of the directory group, for example `Finance`. 3. Leave it empty. 1. Open the group's **Projects** tab. 2. Add the projects it should grant, each with a role. See [Manage Groups](/secure/identity-and-access/roles-and-groups/groups#assign-a-group-to-a-project). When the IdP pushes `Finance`, StackOne turns the empty group into the synced one and keeps its assignments. Its members gain that access as they are pushed. A StackOne group that already has members is never taken over. If the IdP pushes a group with the same name, StackOne creates a second group, tagged **Synced**, and leaves yours untouched. To end up with one `Finance` group, remove the members from yours before the push, or push the directory group under a different name. ## Push groups from the identity provider Push groups from the app's **Push Groups** tab. Provision the groups assigned to the application. ## What changes when | In the identity provider | In StackOne | |---------------------------|-------------| | A group is pushed for the first time. | A synced group appears, or an empty group of the same name becomes the synced group and keeps its access. | | A member is added to or removed from the group. | The membership updates, and the access the group grants follows. | | The group is renamed. | The group is renamed. Its assignments stay. | | The group is deleted, or its push is unlinked and the group deleted with it. | The group is deleted in StackOne. Its members lose the access it granted. | | A member is deactivated or unassigned from the application. | They leave every synced group, along with the rest of their access. If the IdP reactivates them, their memberships return. | If you stop pushing a group but keep it in StackOne, it stays a synced group and can't be edited until you unlink SCIM Provisioning. Delete it from the IdP's push instead, or unlink SCIM Provisioning to get every synced group back. ## When SCIM Provisioning is unlinked or replaced Unlinking SCIM Provisioning, or deleting the SSO connection it's on, hands every synced group back to you. Each becomes a normal group that keeps its members and its project and account assignments, and you can edit it again. Nobody loses access. If you link SCIM Provisioning again, on the same connection or a new one, a pushed group with the same name takes that group back as a synced group, members and assignments intact, rather than creating a second copy. ## Limits - A group push can contain at most **1,000** direct members. StackOne rejects larger pushes, and the IdP reports the error. - Synced group names must be unique within the SCIM Provisioning connection. A push that reuses the name of another synced group is rejected. A group you created by hand can share the name, which is how the takeover above works. - Members must already be provisioned. A push that lists someone SCIM Provisioning doesn't know is rejected until that person is assigned to the StackOne application and provisioned. ## Next steps Assign synced groups to projects and accounts, and manage groups created by hand. How provisioning works and how it attaches to the SSO connection. # Roles and Groups Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/overview Give each user the access they need, from the whole organization down to a single linked account. Access follows the structure of the [organization](/gateway/concepts/organizations-and-projects). The organization holds projects, and each project holds its [connector profiles](/gateway/concepts/connector-profiles) and [linked accounts](/gateway/concepts/linked-accounts). Start from what the person needs: Let someone run the organization, or limit them to the projects they're added to. Hand someone a project, let a team connect their own accounts, or give read-only access. Limit who can link accounts through a sensitive connector profile. Let several people work through one linked account. Give the same roles to many people at once, and change them in one place. ## Give someone access to a provider A user can reach a provider by linking their own account through a connector profile, or by using an account someone else has already linked: | | [Connector Profile Access](/secure/identity-and-access/roles-and-groups/connector-profile-access) | [Shared Accounts](/secure/identity-and-access/roles-and-groups/shared-accounts) | |---|---|---| | Question it answers | Who may connect? | Who may use this connection? | | Whose credentials are used | Each user's own | The account owner's | | What gets created | A new linked account per user | Nothing new, just access to an existing one | | Typical reason | The configuration is privileged or sensitive | One login should serve several people | Use neither if: Everyone in the company books meetings from their own calendar. 1. Leave the calendar connector profile **Shared**. 2. Give each person **Project Member** on the project, as described in [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles). 3. Each person links their own account. Other Project Members can't use it unless it's shared with them. Use [Connector Profile Access](/secure/identity-and-access/roles-and-groups/connector-profile-access) if: A sales team of account executives, with two sales managers who also fix records in bulk. 1. Create two CRM connector profiles: one with admin scopes, and one with read-only scopes. 2. Restrict the admin-scoped profile, and leave the read-only one **Shared**. 3. Grant the sales managers **Connector Profile Member** on the admin-scoped profile. 4. Each manager links their own CRM account through the admin-scoped profile. 5. Everyone else links through the read-only profile. An HR team that handles payroll. 1. Restrict the HR connector profile that reaches payroll data. 2. Grant the HR team's group **Connector Profile Member** on it. 3. Only the HR team can link accounts through it. Use [Shared Accounts](/secure/identity-and-access/roles-and-groups/shared-accounts) if: A support lead and a team of agents who all answer customers from one shared inbox. 1. The support lead links the mailbox once. 2. They grant each agent **Account Member** on it. 3. Agents send replies through the mailbox without needing its password. A team of analysts sharing the company's single licensed seat on a reporting tool. 1. The person who links the reporting tool's single seat becomes its **Account Admin**. 2. They grant the analysts **Account Member** on it. 3. Everyone runs reports through that one seat. Use both if: The head of talent holds the only admin login for the recruiting system. Two recruiters need to use it, without connecting their own. 1. Restrict the recruiting system's connector profile to the head of talent, as **Connector Profile Member**. 2. The head of talent links the admin login through it. 3. They grant the two recruiters **Account Member** on that linked account. ## Which role applies A user's effective role on a resource is the **strongest** role they hold there. ### Roles from groups When a user holds one role directly and another through a group, the stronger one applies. For example: | Direct role | Group's role | Effective role | |-------------|--------------|----------------| | Project Viewer | Project Admin | **Project Admin** | | Project Member | Project Viewer | **Project Member** | To see each member's effective role on a project, open **Project Settings > Access**. ### Roles inherited by accounts An account also inherits access from the organization and from its parent project. Users with the following roles can access an account without being in its **Users** list: | Their standing | Inherited account access | |------|------| | **Organization Admin** | **Account Admin** on every account in the organization | | **Project Admin**, directly or through a group | **Account Admin** on every account under that project | | **Project Viewer**, directly or through a group | View every linked account under that project, but not run actions with them | A **Project Member** inherits nothing. They see only the accounts they linked and any they've been granted access to. ## Explicit account access By default, Organization Admins and Project Admins are **Account Admin** on every account they can reach, so they can run actions with anyone's linked account. **Explicit account access** removes that. With it enabled, admins can view every account, but need a grant to do more: | To | They need | |----|-----------| | Run actions on an account | **Account Member** | | Reconnect, edit, delete, or manage who has access | **Account Admin** | Explicit account access isn't a setting in the dashboard. Contact StackOne to enable it for the organization. # Organization Roles Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/organization-roles Decide who runs the organization, and who only reaches the projects they're added to. Every user in the [organization](/gateway/concepts/organizations-and-projects#organization) is either an **Organization Admin** or an **Organization Member**: | Role | Access | |------|--------| | **Organization Admin** | Manage and view everything in the organization: members, security settings, and every project with its connector profiles and linked accounts. | | **Organization Member** | Only the projects they're granted access to, directly or through a group. **Organization > Manage Team** is hidden from them. | **Organization Admins** can't link accounts through a [restricted connector profile](/secure/identity-and-access/roles-and-groups/connector-profile-access) without a grant. If [explicit account access](/secure/identity-and-access/roles-and-groups/overview#explicit-account-access) is enabled, they can only view other people's accounts until granted a role on them.

Organization roles shown for two users. User A, an Organization Admin, manages members and security settings and everything in Project 1 and Project 2. User B, an Organization Member who is a Project Member on Project 1, has no access to members and security settings or to Project 2. In Project 1, User B can link accounts through connector profiles and manages the account they linked, but has no access to the account User D linked.

An **Organization Admin** can change a user's role at any time on the **Users** tab of [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team). ## Related Give people access to a project, from running it to only viewing it. Invite users and change their roles. # Project Roles Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/project-roles Hand someone a project to run, let a team connect their own accounts, or give read-only access. Project-level RBAC is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Apart from **Organization Admins**, a user can only reach a [project](/gateway/concepts/organizations-and-projects#projects) once they're given a role on it: | Role | Access | |------|--------| | **Project Admin** | Manage everything in the project: every linked account, API keys, webhooks, and who has access. | | **Project Member** | Link their own accounts, and use and manage them. | | **Project Viewer** | See how everything in the project is set up, without changing anything. | **Organization Admins** act as **Project Admin** on every project, without being added to it. Add people to a project and choose their role in **Project Settings > Access**, or give a whole group a role with [Assign a group to a project](/secure/identity-and-access/roles-and-groups/groups#assign-a-group-to-a-project).

Project roles shown for three users on Project 1. User A, the Project Admin, manages connector profiles and every linked account. User B, a Project Member, can link accounts through connector profiles, manages the account they linked, and has no access to the account User D linked. User C, a Project Viewer, can view connector profiles and every linked account. None of them can reach members and security settings or Project 2.

## What each role can do | Resource | Project Admin | Project Member | Project Viewer | |----------|---------------|--------|--------| | [Linked accounts](/gateway/concepts/linked-accounts) | Link, edit, re-authenticate, suspend, delete, and run requests against any account | Link their own accounts, then edit, delete, and run requests against those | View status and details | | [Connector profiles](/gateway/concepts/connector-profiles) | Create, configure, scope actions and events, and delete | Create their own, which they then manage, and link accounts through shared ones | View authentication type and enabled actions of shared profiles | | [MCP connectors](/connect/managing-connectors/adding-mcp-connectors) | Add, and enable ones a Project Member added | Add one by linking their account to it. The connector and the account stay disabled until a Project Admin enables them | View | | [Request logs](/connect/troubleshooting) | View | View for their own accounts and accounts shared with them | View | | [API keys](/embed/api-keys) | Create, scope, and revoke | No access | No access | | [Webhooks](/connect/webhooks) | Create, route events, and delete | No access | No access | | Project settings | Manage all settings | No access | No access | If [explicit account access](/secure/identity-and-access/roles-and-groups/overview#explicit-account-access) is enabled, a **Project Admin** can only view other people's accounts until granted a role on them. ## Related Which accounts a Project Member can hand to an AI platform. Limit who can link accounts through a sensitive connector profile. Let several people work through one linked account. # Connector Profile Access Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/connector-profile-access Control sensitive connector profiles by restricting who can link accounts through them. Connector Profile Access is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). When someone links an account, they only see the [connector profiles](/gateway/concepts/connector-profiles) they're allowed to link through. Each profile is either **Shared** or **Restricted**: | Access | Who can link accounts through the profile | |--------|-------------------------------------------| | **Shared** | Every **Project Admin** and **Project Member** in the [project](/gateway/concepts/organizations-and-projects), and every **Organization Admin**. | | **Restricted** | Only the users and [groups](/secure/identity-and-access/roles-and-groups/groups) granted access on the profile. | Project Admins can still view, edit and delete a restricted profile. ## When to restrict a connector profile Restrict a profile when its configuration is sensitive and only some people should connect through it. Each of them still links their own account. A user can reach a provider by linking their own account through a connector profile, or by using an account someone else has already linked: | | [Connector Profile Access](/secure/identity-and-access/roles-and-groups/connector-profile-access) | [Shared Accounts](/secure/identity-and-access/roles-and-groups/shared-accounts) | |---|---|---| | Question it answers | Who may connect? | Who may use this connection? | | Whose credentials are used | Each user's own | The account owner's | | What gets created | A new linked account per user | Nothing new, just access to an existing one | | Typical reason | The configuration is privileged or sensitive | One login should serve several people | Example cases: A sales team of account executives, with two sales managers who also fix records in bulk. 1. Create two CRM connector profiles: one with admin scopes, and one with read-only scopes. 2. Restrict the admin-scoped profile, and leave the read-only one **Shared**. 3. Grant the sales managers **Connector Profile Member** on the admin-scoped profile. 4. Each manager links their own CRM account through the admin-scoped profile. 5. Everyone else links through the read-only profile. An HR team that handles payroll. 1. Restrict the HR connector profile that reaches payroll data. 2. Grant the HR team's group **Connector Profile Member** on it. 3. Only the HR team can link accounts through it. ## Access to a restricted connector profile A grant gives a user or group one of two roles, **Connector Profile Admin** or **Connector Profile Member**. On a restricted connector profile: | Capability | Project or Organization Admin, no grant | Project Member or Viewer, no grant | Connector Profile Member | Connector Profile Admin | |---|:---:|:---:|:---:|:---:| | **View the profile and its configuration** | Yes | Only if an account they can access was linked through it | Yes | Yes | | **Link accounts through it** | No | No | Yes | Yes | | **Edit its configuration** | Yes | No | No | Yes | | **Delete it** | Yes | No | No | Yes | | **Manage its access** | No | No | No | Yes | | **Enable or disable it** | Yes | No | No | No |

## Restrict a connector profile Restricting a shared profile needs **Project Admin** or **Organization Admin**. Once it's restricted, only a **Connector Profile Admin** can change its access. 1. In [**Connectors**](https://app.stackone.com/connectors), open the connector and select the profile's card. 2. Select its **Access** tab. Under **Who can use this profile**, change the selector from **Shared** to **Restricted**. You become its **Connector Profile Admin** when you save, so you can't lock yourself out. Accounts already linked through the profile stay linked, and can still be re-authenticated through it without a grant. 1. On the **Users** view, use **Add users** to pick each person. 2. On the **Groups** view, use **Add groups** to pick each group. 3. Set each row's role to **Admin** (Connector Profile Admin) or **Member** (Connector Profile Member). **Revoke** removes a row. Click **Save Access** in the bar at the bottom of the page. **Cancel** discards the changes.

A group's grant covers everyone in it, and follows the group as people join or leave. See [Groups](/secure/identity-and-access/roles-and-groups/groups). To change access later, a **Connector Profile Admin** edits the same **Access** tab and saves. A restricted profile must keep at least one **Connector Profile Admin**, so hand the role to someone else in the same save, or switch the profile back to **Shared**. ## The default for new connector profiles Each **project** has a **Default Access** setting that decides whether connector profiles created from then on start **Shared** or **Restricted**. Only an **Organization Admin** can change the default: 1. Go to [**Project Settings > Connector Profiles**](https://app.stackone.com/settings/connector-profiles). 2. Under **Default Access**, choose **Shared** or **Restricted**. 3. Click **Save**. ## Related Choose which of a profile's actions and events are exposed. Grant many users the same access at once with reusable groups. Connect the provider accounts your agents act on. Add people to the organization, and remove their access when they leave. # Shared Accounts Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/shared-accounts Let several people work through one linked account instead of each linking their own. Account sharing is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Share an account when several people should work through one login, rather than each linking their own. Everyone acts through the same login, without needing its credentials. A user can reach a provider by linking their own account through a connector profile, or by using an account someone else has already linked: | | [Connector Profile Access](/secure/identity-and-access/roles-and-groups/connector-profile-access) | [Shared Accounts](/secure/identity-and-access/roles-and-groups/shared-accounts) | |---|---|---| | Question it answers | Who may connect? | Who may use this connection? | | Whose credentials are used | Each user's own | The account owner's | | What gets created | A new linked account per user | Nothing new, just access to an existing one | | Typical reason | The configuration is privileged or sensitive | One login should serve several people | Example cases: A support lead and a team of agents who all answer customers from one shared inbox. 1. The support lead links the mailbox once. 2. They grant each agent **Account Member** on it. 3. Agents send replies through the mailbox without needing its password. A team of analysts sharing the company's single licensed seat on a reporting tool. 1. The person who links the reporting tool's single seat becomes its **Account Admin**. 2. They grant the analysts **Account Member** on it. 3. Everyone runs reports through that one seat. The head of talent holds the only admin login for the recruiting system. Two recruiters need to use it, without connecting their own. 1. Restrict the recruiting system's connector profile to the head of talent, as **Connector Profile Member**. 2. The head of talent links the admin login through it. 3. They grant the two recruiters **Account Member** on that linked account. To share an account another user linked, grant a role on that [linked account](/gateway/concepts/linked-accounts): | Role | Access | |------|--------| | **Account Admin** | Run actions, edit, delete, re-authenticate, and manage who else has access. | | **Account Member** | Run actions only. | Account roles shown for two Project Members of Project 1, granted roles on the account User C linked. User A, the Account Admin, manages it. User B, the Account Member, uses it. Both can link accounts through the project's connector profiles, and neither has access to the account User D linked, members and security settings, or Project 2.

Account roles shown for two Project Members of Project 1, granted roles on the account User C linked. User A, the Account Admin, manages it. User B, the Account Member, uses it. Both can link accounts through the project's connector profiles, and neither has access to the account User D linked, members and security settings, or Project 2.

## Share an account Before sharing an account: - You need **Account Admin** on it. - The person must already be in the account's project, or be an **Organization Admin**. 1. Go to [**Accounts**](https://app.stackone.com/accounts) and open the account. 2. Select its **Access** tab. 3. Click **Add Users**, select the people, and choose **Account Admin** or **Account Member**. To share it with a whole group, see [Assign a group to an account](/secure/identity-and-access/roles-and-groups/groups#assign-a-group-to-an-account). ## Related Control who can connect through a connector profile in the first place. How a shared account's roles combine with project roles and groups. # Groups Source: https://docs.stackone.com/secure/identity-and-access/roles-and-groups/groups Give the same roles to many people at once, and change them in one place. A group with roles applied gives the same access to people who do the same job, such as a team or department. People who join or leave the group gain or lose that access automatically. Groups can be managed either: - [**Manual groups**](#manual-groups) (see below). - **Synced from the identity provider**, through [SCIM Groups](/secure/identity-and-access/manage-team/scim/groups). ## Manual groups These are the groups created in StackOne. Groups from the identity provider are managed there instead. ### Create a group Only **Organization Admins** can create groups, manage their members, and delete them. Go to [**Organization > Manage Team**](https://app.stackone.com/organization/manage_team) and select the **Groups** tab. The Groups tab in Manage Team listing each group with its current user count.

The Groups tab in Manage Team listing each group with its current user count.

1. Click **Create group** to open the panel. 2. Enter a **Name**, for example a department, team or function. You can rename the group later with **Edit Details**. 3. Optionally, add **Users** from the organization. You can add more later. 4. Click **Create group** to finish. The Create group side panel with a required Name field and an optional Users selector.

The Create group side panel with a required Name field and an optional Users selector.

### Manage group membership Open the group from the **Groups** tab. A group's Users tab listing its users, each with a Remove action, and an Add users button.

- To add people, click **Add users**, select them, and confirm. - To remove someone, click **Remove** on their row and confirm. They lose any access the group gave them. ### Delete a group 1. Open the group from the **Groups** tab and click **Delete**. 2. Type the group's name, then click **Delete** to confirm. This can't be undone, and the group's members lose any access it gave them. ## Assign a group to a project Assigning a group to a project needs **Organization Admin** or **Project Admin**. Start from the project to add several groups to it at once, or from the group to add it to several projects: 1. Go to [**Project Settings > Access**](https://app.stackone.com/settings/members). 2. Switch the view from **Users** to **Groups**. Project Settings > Access with the Users / Groups switch set to Groups, showing each assigned group with its role and a Revoke action.

Project Settings > Access with the Users / Groups switch set to Groups, showing each assigned group with its role and a Revoke action.

1. Click **Add Groups**. 2. Select one or more groups. 3. Choose a **Role**. It defaults to **Project Member**. See [Project Roles](/secure/identity-and-access/roles-and-groups/project-roles) for what each role allows. The Add Groups side panel on a project's Access view, with a Groups selector and a Role dropdown set to Project Member.

The Add Groups side panel on a project's Access view, with a Groups selector and a Role dropdown set to Project Member.

Confirm the selection to add the groups. Every member of each selected group gains the chosen role on the project. 1. Open the group and select its **Projects** tab. 2. Click **Add project**, then select a **Project** and a **Role**. The role defaults to **Project Member**. 3. Click **Add project** to confirm. ## Assign a group to an account Before assigning a group to an account: - You need **Account Admin** on that account. - The group must already be assigned to the account's project. See [Assign a group to a project](#assign-a-group-to-a-project). Organization Admins and Project Admins are **Account Admin** on every account by default, unless [explicit account access](/secure/identity-and-access/roles-and-groups/overview#explicit-account-access) is enabled. 1. Go to [**Accounts**](https://app.stackone.com/accounts) and open the account. 2. Select its **Access** tab. 3. Switch the view to **Groups**. 1. Click **Add Groups**. 2. Select one or more groups. 3. Choose **Account Admin** or **Account Member**. It defaults to **Account Member**. See [Shared Accounts](/secure/identity-and-access/roles-and-groups/shared-accounts) for what each role allows. Confirm the selection to add the groups. Every member of each selected group gains the chosen role on the account. ## Change or remove a group's access Open the **Groups** view on the project or account, then: - To change the group's role, pick a new role on its row. - To remove the group's access, click **Revoke** on its row and confirm. Access a group gets through the project isn't listed on the account. Change or revoke it on the project instead. Revoking a group from a project also revokes it from every account in that project. To stop you locking yourself out, you can't revoke a group that is your only access to a project. **Organization Admins** can, because they always have access to every project. # IP Restrictions Source: https://docs.stackone.com/secure/ip-restrictions Restrict a project's API access to specific IP addresses, ranges, or CIDR blocks. IP allow-listing is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Restrict API access to specific IP addresses under **Project Settings → IP Restrictions**. Entries can take three formats: This setting controls which source IPs can call your project's StackOne API. To allow StackOne to reach a provider API or webhook endpoint behind a firewall, use [StackOne's outbound IP addresses](/gateway/concepts/connector-profiles#connection-issues-behind-a-firewall). | Format | Example | |--------|---------| | Single IP | `192.168.1.100` | | Range | `192.168.1.100-192.168.1.150` | | CIDR | `192.168.1.0/24` | If your network uses a NAT gateway, allow the gateway's external IP to permit all internal traffic. With no allowlist configured, all IPs are allowed. Once you add entries, only those IPs can access your project's API. # Observability Source: https://docs.stackone.com/secure/observability Track activity, redact personal data, and control how long request data is kept. StackOne records activity at two levels: security logs at the organization level and request logs at the project level. Together they cover who signed in and what calls your project made. ## What's logged | Log | Level | Covers | |-----|-------|--------| | Security logs | Organization | Every login attempt, success or failure. | | Request logs | Project | API and webhook requests, with status, payload detail, and optional PII redaction. See [Request Logs](/connect/troubleshooting). | ## Security logs Security logs are a record of every login attempt, success or failure, for monitoring and audit. Open them under [**Organization > Security > Logs**](https://app.stackone.com/organization/security/logs). Security Logs page listing login attempts with their outcomes

Security Logs page listing login attempts with their outcomes

## Advanced Logs Advanced Logs stores the request and response bodies of your project's calls, so you can debug a failed request step by step. See [Request Logs](/features/observability/request-log-debugging#advanced-logs-request-and-response-bodies) for how to read them. Open **Project Settings → Advanced Logs** to configure it. Settings apply to the whole project. Advanced Logs is **off by default**. Turn it on before detailed request logging starts. Advanced Logs settings: status, storage, background operations, and PII redaction

Advanced Logs settings: status, storage, background operations, and PII redaction

### Settings | Setting | Description | Default | |---|---|---| | **Status** | Turns Advanced Logs on or off for the project. | Off | | **Storage Settings** | **Error Data Only** stores bodies only for failed requests (HTTP status 400 or above). **All Data** stores them for every request. | Error Data Only | | **Include Background Operations** | Also stores operations StackOne runs itself, such as token refreshes, alongside the requests your users make. | Off | | **Redact personal information (PII)** | Replaces personal data in stored bodies. See [PII redaction](#pii-redaction). | Off | | **Storage Duration** | How long logs are kept before they are deleted: 1, 7, or 30 days. | 30 days | | **Automatically Disable on Date** | Turns Advanced Logs off on the date you pick, so logging you turned on to debug an issue does not keep running. | None | The other settings can only be changed while **Status** is on. Advanced Logs settings: storage duration and automatic disable date

Advanced Logs settings: storage duration and automatic disable date

Retention changes apply only to new logs. Existing logs keep the retention they were stored with. ### PII redaction PII redaction removes personally identifiable information (PII) from stored bodies. To redact PII from tool inputs and responses, see [PII Redaction](/secure/pii-redaction). When **Redact personal information (PII)** is on, StackOne scans each body before the log is written and replaces each personal value it detects with a tag naming its type, such as `` or ``. Credential-like tokens the patterns catch have no type and become ``; named credential fields follow the **Credentials** rule below. Only the redacted copy is stored. - **Detection.** Patterns catch email addresses and credential-like tokens. A model finds names, phone numbers, postal addresses, government ID numbers, payment card numbers, and other personal data. - **Scope.** Request and response bodies only. Log metadata such as the path, status code, connector, and Linked Account stays intact, so logs remain searchable. - **Coverage.** The bodies of action call logs. - **Applies to new logs only.** Logs that are already stored are not changed. - **Credentials.** Fields whose names match a fixed list of credential names, such as `password`, `token`, `api_key`, `client_secret`, and `authorization`, are masked in every stored body whether or not PII redaction is on. The value is replaced with `**redacted**`, followed by its last five characters when it is longer than 10 characters. StackOne may not catch every instance of personal data. Don't treat redaction as the only control for regulated data. For compliance requirements beyond these settings, contact your StackOne account manager. # Self-Hosted Deployment Source: https://docs.stackone.com/secure/self-hosted-deployment Run StackOne in your own environment for full data residency. Self-hosted deployment is only available on certain plans. {detail} See [plans and pricing](https://www.stackone.com/pricing/). Most customers use StackOne's managed cloud, where you choose a [region](/gateway/concepts/organizations-and-projects) for data residency at the project level. Self-hosting runs StackOne inside your own infrastructure instead. The key advantage: your integration data never leaves your environment, meeting strict data-residency, sovereignty, and compliance requirements that the managed regions don't cover. Reach your StackOne account manager or email support@stackone.com to scope a deployment. # Connectors Source: https://docs.stackone.com/connectors/introduction Explore 560+ connectors and 35000+ actions available through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A. Browse StackOne's pre-built connectors — each connector page shows its actions, authentication guides, and events. New connectors ship continuously, and any system can be added on request or [built yourself](/connector-building/overview). To connect your first system and run an action, follow the [Quickstart](/gateway/quickstart). Need a system or action that isn't listed? [Talk to StackOne](https://www.stackone.com/demo) and our team builds and maintains it for you: - **Fast turnaround** — typically days, not weeks (when API access is provided) - **Full support** — we handle API mapping, auth, and testing - **QA pipeline** — automated tests, AI-driven optimization, and manual verification - **Fork & customize** — optionally fork and edit actions after delivery Prefer to build it yourself? Start with [Connector Building](/connector-building/overview). StackOne builds connectors by analyzing **thousands of documented APIs** using AI agents and manual QA. Each connector's actions are automatically tested, then **manually verified by StackOne**. Evaluation data continuously improves action quality. ## All Connectors --- # 15Five Source: https://docs.stackone.com/connectors/15five/index How to set up the 15Five connector, plus the actions that are available.

Previewv4.0.0

See changelog

61 actions · 1 auth method

HRIS

Previewv1.2.0

See changelog

24 actions · 1 auth method

IAM

v1.2.1

See changelog

78 actions · 38 events · 1 auth method

LMS

v1.4.0

See changelog

59 actions · 1 auth method

HRIS

Betav0.2.0

See changelog

62 actions · 1 auth method

AI IAM

v1.1.0

See changelog

24 actions · 1 auth method

HRIS

Betav1.0.0

28 actions · 1 auth method

HRIS

Previewv1.1.3

See changelog

119 actions · 1 auth method

Device Management

Betav1.1.0

See changelog

67 actions · 1 auth method

CRM Project Management Ticketing Billing

v1.3.0

See changelog

40 actions · 1 auth method

CRM Marketing

Previewv0.1.1

See changelog

55 actions · 1 event · 1 auth method

IAM

Betav1.1.0

See changelog

61 actions · 1 auth method

E-Commerce

Betav1.1.0

See changelog

52 actions · 1 auth method

CMS

v1.1.0

See changelog

72 actions · 1 auth method

LMS

Previewv1.2.1

See changelog

48 actions · 3 events · 1 auth method

Documents IAM

Previewv1.5.0

See changelog

53 actions · 31 events · 1 auth method

HRIS ATS

Betav0.2.0

See changelog

71 actions · 1 auth method

HRIS ATS

Previewv0.1.1

See changelog

19 actions · 1 auth method

Payments IAM

Previewv1.2.2

See changelog

43 actions · 1 auth method

CRM IAM

v1.2.0

See changelog

91 actions · 34 events · 2 auth methods

Project Management

Previewv0.1.1

See changelog

15 actions · 1 auth method

Data Integration IAM

Previewv1.2.0

See changelog

82 actions · 8 events · 1 auth method

Telephony IAM

v1.2.0

See changelog

39 actions · 1 auth method

Marketing

v1.3.0

See changelog

33 actions · 2 auth methods

Databases IAM

v1.0.0

See changelog

39 actions · 1 auth method

v1.1.0

See changelog

42 actions · 1 auth method

Previewv1.1.0

See changelog

89 actions · 1 auth method

Storage

v2.3.1

See changelog

54 actions · 1 auth method

CRM IAM

v1.3.0

See changelog

63 actions · 4 events · 1 auth method

Analytics IAM

Betav1.1.0

See changelog

43 actions · 2 auth methods

IAM

v2.3.0

See changelog

29 actions · 38 events · 2 auth methods

AI IAM

v1.7.0

See changelog

57 actions · 1 auth method

CRM IAM

Previewv0.1.0

See changelog

14 actions · 1 auth method

IAM Device Management

Betav1.1.0

See changelog

25 actions · 1 auth method

ATS

v1.3.0

See changelog

70 actions · 1 auth method

Accounting IAM

v1.1.0

See changelog

37 actions · 4 events · 1 auth method

LMS

v1.1.0

See changelog

8 actions · 1 auth method

v2.0.0

See changelog

126 actions · 10 events · 3 auth methods

Project Management

v3.0.3

See changelog

138 actions · 1 auth method

ATS

v1.1.0

See changelog

19 actions · 1 auth method

Marketing Messaging E-Commerce

v1.4.0

See changelog

68 actions · 27 events · 2 auth methods

CRM IAM

v1.3.0

See changelog

87 actions · 25 events · 2 auth methods

IAM

Previewv4.0.1

See changelog

65 actions · 2 auth methods

IAM

v1.0.0

See changelog

62 actions · 5 events · 1 auth method

Billing

v1.2.0

See changelog

50 actions · 1 event · 1 auth method

Observability

v1.0.0

See changelog

29 actions · 1 auth method

Documents

Previewv1.0.0

66 actions · 1 auth method

Infrastructure

v1.2.0

See changelog

27 actions · 11 events · 1 auth method

Storage

Previewv1.2.0

See changelog

185 actions · 14 events · 2 auth methods

Project Management Ticketing Developer Tools IAM

v1.2.0

See changelog

30 actions · 15 events · 1 auth method

v2.1.1

See changelog

107 actions · 3 events · 2 auth methods

HRIS ATS

v3.0.0

See changelog

133 actions · 45 events · 1 auth method

Project Management IAM

Betav2.0.0

See changelog

38 actions · 4 auth methods

E-Commerce

Betav0.2.0

See changelog

25 actions · 1 auth method

Messaging

Betav1.1.0

See changelog

75 actions · 1 auth method

Vendor Management System

Previewv0.1.2

See changelog

8 actions · 1 auth method

IAM Observability

Previewv1.2.0

See changelog

103 actions · 1 auth method

Accounting IAM

Previewv1.1.0

See changelog

120 actions · 1 auth method

E-Commerce Marketing

Previewv0.3.0

See changelog

66 actions · 2 auth methods

Accounting

Previewv1.1.0

See changelog

60 actions · 1 auth method

Advertising

Previewv2.3.1

See changelog

142 actions · 26 events · 2 auth methods

Developer Tools IAM

v1.1.0

See changelog

85 actions · 2 auth methods

Marketing

Betav1.1.0

See changelog

24 actions · 1 auth method

IAM

Betav1.1.0

See changelog

104 actions · 1 auth method

CRM

Betav1.1.0

See changelog

37 actions · 1 auth method

ITSM Ticketing

v2.0.0

See changelog

96 actions · 36 events · 1 auth method

Storage IAM

v2.1.0

See changelog

47 actions · 1 auth method

LMS

Previewv1.3.2

See changelog

55 actions · 36 events · 1 auth method

Payments

v1.0.4

See changelog

13 actions · 1 auth method

v1.2.0

See changelog

98 actions · 105 events · 1 auth method

Marketing

v1.1.0

See changelog

42 actions · 1 auth method

HRIS

v1.1.0

See changelog

47 actions · 10 events · 1 auth method

ATS

v2.3.2

See changelog

70 actions · 18 events · 1 auth method

Marketing IAM

Betav1.1.0

See changelog

4 actions · 1 auth method

HRIS

v1.1.0

See changelog

77 actions · 4 events · 1 auth method

Observability

v2.1.0

See changelog

28 actions · 1 auth method

Developer Tools

v2.2.2

See changelog

80 actions · 2 auth methods

ATS CRM

v2.0.1

See changelog

63 actions · 3 events · 1 auth method

Scheduling IAM

v1.2.0

See changelog

47 actions · 12 events · 2 auth methods

Scheduling IAM

v1.3.0

See changelog

84 actions · 4 events · 2 auth methods

Marketing IAM

Betav1.1.0

See changelog

60 actions · 1 auth method

Accounting

Betav1.1.0

See changelog

45 actions · 1 auth method

Healthcare Billing

v2.0.0

See changelog

36 actions · 2 auth methods

Design IAM

v6.0.0

See changelog

136 actions · 19 events · 2 auth methods

CRM IAM

Betav1.1.0

See changelog

62 actions · 1 auth method

v1.2.0

See changelog

56 actions · 1 auth method

HRIS

Betav1.1.0

See changelog

36 actions · 2 auth methods

HRIS

v1.3.0

See changelog

56 actions · 24 events · 1 auth method

ATS

Betav1.1.0

See changelog

20 actions · 6 events · 1 auth method

ATS

v1.2.0

See changelog

54 actions · 7 events · 1 auth method

HRIS

v1.3.0

See changelog

60 actions · 1 event · 1 auth method

Billing

v1.1.0

See changelog

125 actions · 1 auth method

Billing

v1.1.0

See changelog

22 actions · 1 auth method

HRIS

Betav1.1.0

See changelog

67 actions · 1 auth method

HRIS IAM

v1.3.0

See changelog

68 actions · 20 events · 1 auth method

Observability

Betav1.2.0

See changelog

67 actions · 1 auth method

Background Checks IAM

Previewv0.1.0

See changelog

54 actions · 11 events · 1 auth method

ERP CRM

v1.2.0

See changelog

82 actions · 2 events · 1 auth method

Developer Tools

Betav1.1.0

See changelog

50 actions · 1 auth method

HRIS

Previewv0.1.0

See changelog

44 actions · 1 auth method

v1.2.0

See changelog

95 actions · 28 events · 2 auth methods

Project Management IAM

v1.1.0

See changelog

9 actions · 1 auth method

Healthcare

Previewv1.3.0

See changelog

116 actions · 50 events · 1 auth method

Time Tracking IAM

Betav1.2.0

See changelog

16 actions · 1 auth method

ATS

v1.2.0

See changelog

81 actions · 14 events · 2 auth methods

CRM

Previewv1.2.1

See changelog

150 actions · 1 auth method

Infrastructure Observability IAM Security

Previewv0.1.0

See changelog

8 actions · 1 auth method

Telephony IAM

Betav1.1.0

See changelog

82 actions · 1 auth method

Infrastructure

Betav3.1.0

See changelog

64 actions · 1 auth method

E-Commerce Payments

v1.1.0

See changelog

14 actions · 1 auth method

Betav1.1.0

See changelog

26 actions · 1 auth method

ATS

v1.4.1

See changelog

145 actions · 3 auth methods

Knowledge Management IAM

v2.1.0

See changelog

78 actions · 1 auth method

Marketing

v1.2.0

See changelog

80 actions · 18 events · 2 auth methods

CMS IAM

v2.0.0

See changelog

58 actions · 1 auth method

CRM

v2.2.0

See changelog

21 actions · 30 events · 1 auth method

LMS

Betav0.2.0

See changelog

80 actions · 1 auth method

Accounting Procurement Payments IAM

Previewv1.2.1

See changelog

19 actions · 1 auth method

LMS

Betav0.2.0

See changelog

68 actions · 1 auth method

ATS

Betav1.1.2

See changelog

61 actions · 1 auth method

ATS CRM

Betav0.1.0

See changelog

24 actions · 1 auth method

Betav1.1.0

See changelog

9 actions · 1 auth method

HRIS

Previewv2.2.0

See changelog

57 actions · 72 events · 2 auth methods

Marketing

Betav1.1.0

See changelog

31 actions · 1 auth method

IAM

v1.2.0

See changelog

52 actions · 1 auth method

Developer Tools

Previewv0.1.0

See changelog

5 actions · 1 auth method

v2.0.0

See changelog

72 actions · 3 auth methods

Analytics IAM

v1.3.0

See changelog

51 actions · 6 events · 1 auth method

Analytics

v1.5.0

See changelog

49 actions · 6 events · 2 auth methods

Observability IAM

Betav0.1.0

See changelog

39 actions · 1 auth method

Security

Previewv3.1.0

See changelog

61 actions · 1 auth method

HRIS

Previewv2.1.0

See changelog

92 actions · 55 events · 2 auth methods

HRIS ATS

Betav0.1.0

See changelog

22 actions · 1 auth method

Security

v1.1.0

See changelog

6 actions · 1 auth method

Events

v1.2.0

See changelog

49 actions · 47 events · 1 auth method

HRIS

Betav1.1.0

See changelog

57 actions · 2 auth methods

Telephony

v2.3.0

See changelog

91 actions · 2 auth methods

Messaging IAM

v1.2.0

See changelog

67 actions · 50 events · 1 auth method

v3.0.1

See changelog

66 actions · 33 events · 1 auth method

Customer Support Ticketing

v1.3.0

See changelog

56 actions · 50 events · 1 auth method

LMS

Previewv1.1.2

See changelog

73 actions · 1 auth method

E-Signature IAM

Previewv1.1.0

See changelog

23 actions · 1 auth method

Analytics IAM

Previewv1.1.1

See changelog

64 actions · 1 auth method

IAM

v2.1.1

See changelog

94 actions · 1 auth method

Storage IAM

Previewv2.0.0

See changelog

80 actions · 2 auth methods

E-Signature IAM

v1.0.0

1 action · 1 auth method

Previewv0.2.1

See changelog

39 actions · 1 auth method

IAM

v1.2.1

See changelog

62 actions · 6 events · 1 auth method

Developer Tools

Betav1.0.0

12 actions · 1 auth method

ATS

v1.2.0

See changelog

27 actions · 3 events · 1 auth method

LMS

v1.2.0

See changelog

48 actions · 14 events · 1 auth method

Logistics

Previewv1.2.0

See changelog

38 actions · 21 events · 2 auth methods

Storage

Previewv0.1.1

See changelog

160 actions · 31 events · 3 auth methods

Previewv1.3.4

See changelog

62 actions · 1 auth method

Infrastructure IAM

Previewv0.3.0

See changelog

182 actions · 8 events · 1 auth method

AI IAM

v2.1.0

See changelog

52 actions · 46 events · 1 auth method

HRIS

Betav0.3.0

See changelog

104 actions · 1 auth method

ERP Logistics Accounting Documents Procurement

v1.3.0

See changelog

49 actions · 2 auth methods

IAM

Previewv1.1.0

See changelog

92 actions · 1 auth method

ATS

Betav0.1.0

See changelog

95 actions · 1 auth method

HRIS

Previewv2.0.4

See changelog

90 actions · 15 events · 2 auth methods

Events IAM

Betav0.2.0

See changelog

35 actions · 1 auth method

v1.2.1

See changelog

27 actions · 1 auth method

Expense Management IAM

v1.3.0

See changelog

42 actions · 2 events · 1 auth method

Developer Tools

Previewv1.0.1

See changelog

80 actions · 1 auth method

Advertising

Previewv1.0.1

See changelog

53 actions · 2 auth methods

Advertising

Previewv1.0.1

See changelog

8 actions · 2 auth methods

Advertising

Previewv1.1.0

See changelog

127 actions · 2 auth methods

HRIS ATS

v3.0.0

See changelog

56 actions · 11 events · 1 auth method

Accounting

v1.2.1

See changelog

59 actions · 42 events · 1 auth method

E-Commerce

v1.3.0

See changelog

14 actions · 2 events · 1 auth method

IAM Notetaker

Betav1.1.0

See changelog

49 actions · 2 auth methods

Surveys

v2.0.0

See changelog

57 actions · 2 auth methods

Design IAM

Betav1.1.1

See changelog

53 actions · 15 events · 1 auth method

IAM Legal

Betav0.2.0

See changelog

42 actions · 1 auth method

v1.1.0

See changelog

36 actions · 1 auth method

Developer Tools IAM Databases

v1.4.1

See changelog

25 actions · 4 events · 1 auth method

Notetaker IAM

Previewv1.3.0

See changelog

172 actions · 16 events · 1 auth method

Data Integration IAM

Betav1.1.0

See changelog

29 actions · 1 auth method

ATS

Betav0.2.0

See changelog

64 actions · 1 auth method

HRIS

Betav1.1.0

See changelog

62 actions · 1 auth method

ATS IAM

v2.1.1

See changelog

28 actions · 1 auth method

HRIS

Previewv1.1.1

See changelog

105 actions · 1 auth method

Accounting

Previewv2.1.1

See changelog

89 actions · 1 auth method

Accounting IAM

Previewv0.1.1

See changelog

14 actions · 1 auth method

Customer Support IAM

v1.2.0

See changelog

73 actions · 2 events · 1 auth method

Customer Support Ticketing

Previewv1.4.0

See changelog

125 actions · 1 event · 1 auth method

CRM IAM

Previewv1.3.0

See changelog

101 actions · 1 event · 1 auth method

ITSM Ticketing IAM

v1.4.0

See changelog

66 actions · 20 events · 1 auth method

Customer Support Ticketing IAM

Betav1.1.0

See changelog

34 actions · 1 auth method

ATS

v1.5.0

See changelog

61 actions · 3 events · 1 auth method

Knowledge Management IAM

v3.6.1

See changelog

123 actions · 25 events · 4 auth methods

Developer Tools IAM

Previewv1.5.0

See changelog

156 actions · 49 events · 3 auth methods

Developer Tools IAM

Betav1.1.0

See changelog

65 actions · 1 auth method

Customer Support Ticketing

Previewv0.1.1

See changelog

87 actions · 2 auth methods

Knowledge Management AI

Previewv2.1.1

See changelog

24 actions · 1 auth method

HRIS

v1.1.0

See changelog

42 actions · 1 auth method

Messaging

Previewv2.2.1

See changelog

70 actions · 14 events · 1 auth method

LMS

v2.0.0

See changelog

66 actions · 34 events · 2 auth methods

Payments

Betav1.0.0

11 actions · 1 auth method

LMS

v2.1.0

See changelog

41 actions · 1 event · 2 auth methods

CRM IAM

Betav1.0.0

52 actions · 1 auth method

Advertising

v1.1.0

See changelog

33 actions · 1 auth method

Analytics

v2.1.2

See changelog

41 actions · 1 auth method

Databases Analytics

v1.2.0

See changelog

37 actions · 5 events · 1 auth method

Scheduling

v2.2.0

See changelog

32 actions · 1 auth method

Messaging

Previewv1.0.1

40 actions · 1 auth method

Internal

Previewv2.1.0

50 actions · 1 auth method

Infrastructure Databases Internal

Previewv1.1.0

See changelog

46 actions · 4 events · 1 auth method

Internal Observability

Previewv1.0.0

56 actions · 1 auth method

Security IAM

Previewv1.1.0

See changelog

30 actions · 1 auth method

Storage Internal

v2.1.0

See changelog

21 actions · 1 auth method

Productivity

v1.3.0

See changelog

41 actions · 6 events · 1 auth method

IAM

v1.4.0

See changelog

4 actions · 1 auth method

Documents IAM

v2.1.1

See changelog

64 actions · 2 events · 2 auth methods

Storage IAM

v1.0.1

6 actions · 1 auth method

Surveys

v4.0.0

See changelog

37 actions · 10 events · 2 auth methods

v1.0.0

See changelog

41 actions · 1 auth method

v2.0.1

See changelog

24 actions · 1 auth method

Meetings

Previewv1.2.1

See changelog

10 actions · 1 auth method

Marketing

v1.0.1

17 actions · 1 auth method

Documents

v1.2.0

See changelog

80 actions · 2 events · 1 auth method

E-Commerce

v3.1.0

See changelog

47 actions · 1 auth method

Documents

v2.1.0

See changelog

12 actions · 1 auth method

Productivity

Previewv0.2.0

See changelog

7 actions · 1 auth method

v1.1.2

See changelog

22 actions · 1 auth method

Translation

v1.3.0

See changelog

69 actions · 8 events · 1 auth method

Customer Support Ticketing

Previewv2.1.0

See changelog

61 actions · 1 auth method

Messaging IAM

Previewv1.3.1

See changelog

100 actions · 19 events · 1 auth method

Observability IAM

Previewv0.1.0

See changelog

4 actions · 1 auth method

Notetaker

v1.1.0

See changelog

99 actions · 2 auth methods

ATS

Betav1.1.0

See changelog

20 actions · 1 auth method

v1.2.0

See changelog

96 actions · 24 events · 1 auth method

HRIS

v1.3.1

See changelog

35 actions · 2 events · 1 auth method

HRIS

v1.5.0

See changelog

152 actions · 1 auth method

Developer Tools IAM

Previewv0.1.0

See changelog

83 actions · 2 auth methods

v1.2.0

See changelog

87 actions · 2 auth methods

Time Tracking IAM

Previewv0.1.0

See changelog

19 actions · 1 auth method

CRM

v1.0.3

See changelog

6 actions · 1 auth method

Analytics

v1.2.0

See changelog

36 actions · 28 events · 2 auth methods

Customer Support Ticketing

Previewv0.2.1

See changelog

96 actions · 1 auth method

Device Management

Previewv4.0.1

See changelog

129 actions · 28 events · 2 auth methods

HRIS

## Getting Started Set up a new project or select an existing one. See [Organizations & Projects](/gateway/concepts/organizations-and-projects). Enable the connector and set up a Connector Profile in your project. See [Setup Connector Profile](/gateway/quickstart#setup-connector-profile). Access to a Hibob Service User is required. You can manage Service Users in \[Hibob's \*Integrations\* settings\](https://ap... Connect your HiBob account using OAuth 2.0. You will be redirected to HiBob to authorize access and select which employe... Optionally, configure receiving Events for HiBob into StackOne. Link an account [from the dashboard](/connect/managing-connectors/linking-accounts#link-from-the-dashboard) (or via [StackOne Hub](/embed/account-linking/overview)). See the guide for the authentication type chosen in the Connector Profile: Connect an AI platform to the linked account's actions. See [AI Platforms](/connect/ai-platforms/overview). Other ways to call actions are listed in [Protocols & SDKs](/connect/protocols-and-sdks). ## Actions See https://docs.stackone.com/connectors/hibob/index.md for the full list. ## Events See https://docs.stackone.com/connectors/hibob/index.md for the full list. # HiBob Changelog Source: https://docs.stackone.com/connectors/hibob/changelog Release history for the HiBob connector. Each version lists what changed and which actions were affected. Back to the connector overview, authentication methods, and actions. `documentation` Moved 69 actions from preview to beta. `hibob_add_policy_type_reason_codes`, `hibob_cancel_position`, `hibob_create_bank_account`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_position_opening`, `hibob_create_salary_entry`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_delete_bank_account`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_key_result`, `hibob_delete_position_opening`, `hibob_get_all_company_lists`, `hibob_get_employee`, `hibob_get_goal_type_metadata`, `hibob_get_goals_metadata`, `hibob_get_job_ad`, `hibob_get_job_families`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles`, `hibob_get_job_roles_metadata`, `hibob_get_key_results_metadata`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_get_report_download_url`, `hibob_import_attendance_data`, `hibob_list_bulk_deduction_history`, `hibob_list_bulk_dependents_history`, `hibob_list_bulk_entitlement_history`, `hibob_list_bulk_equities_history`, `hibob_list_bulk_right_to_work_history`, `hibob_list_bulk_variable_history`, `hibob_list_employee_bank_accounts`, `hibob_search_employees`, `hibob_search_goal_types`, `hibob_search_goals`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_key_results`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_update_bank_account`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_key_results_progress`, `hibob_update_position`, `hibob_update_position_budget` `breaking` `bug-fix` `new-actions` Removed employee-table fields that hiBob silently ignores, corrected several field value sets and cursor types, and added six company-wide history actions. `hibob_list_bulk_deduction_history`, `hibob_list_bulk_dependents_history`, `hibob_list_bulk_entitlement_history`, `hibob_list_bulk_equities_history`, `hibob_list_bulk_right_to_work_history`, `hibob_list_bulk_variable_history` `hibob_add_item_to_list`, `hibob_add_policy_type_reason_codes`, `hibob_adjust_time_off_balance`, `hibob_cancel_position`, `hibob_cancel_time_off_request`, `hibob_create_bank_account`, `hibob_create_custom_field`, `hibob_create_employee`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_salary_entry`, `hibob_create_time_off_request`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_create_work_history_entry`, `hibob_delete_custom_field`, `hibob_delete_document_from_confidential_folder`, `hibob_delete_document_from_custom_folder`, `hibob_delete_document_from_shared_folder`, `hibob_delete_employment_entry`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_list_item`, `hibob_delete_position_opening`, `hibob_delete_salary_entry`, `hibob_delete_training_record`, `hibob_delete_variable_payment`, `hibob_delete_work_history_entry`, `hibob_get_all_company_lists`, `hibob_get_company_list_by_name`, `hibob_get_employee`, `hibob_get_employee_avatar`, `hibob_get_employee_time_off_balance`, `hibob_get_job_families`, `hibob_get_job_family_groups`, `hibob_get_job_roles`, `hibob_get_payroll_history`, `hibob_get_report_download_url`, `hibob_get_time_off_request`, `hibob_get_whos_out`, `hibob_get_whos_out_today`, `hibob_import_attendance_data`, `hibob_invite_employee`, `hibob_list_bulk_employment_history`, `hibob_list_bulk_lifecycle_history`, `hibob_list_bulk_salaries_history`, `hibob_list_bulk_work_history`, `hibob_list_employee_documents`, `hibob_list_employee_employment_history`, `hibob_list_employee_equity_grants`, `hibob_list_employee_lifecycle_history`, `hibob_list_employee_salary_history`, `hibob_list_employee_tasks`, `hibob_list_employee_training_records`, `hibob_list_employee_variable_payments`, `hibob_list_employee_work_history`, `hibob_mark_task_complete`, `hibob_search_actual_payments`, `hibob_search_employees`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_terminate_employee`, `hibob_update_bank_account`, `hibob_update_custom_field`, `hibob_update_employee`, `hibob_update_employee_email`, `hibob_update_employee_start_date`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_list_item`, `hibob_update_position`, `hibob_update_position_budget`, `hibob_update_position_opening`, `hibob_update_work_history_entry`, `hibob_upload_document_from_url_to_confidential`, `hibob_upload_document_from_url_to_custom_folder`, `hibob_upload_document_from_url_to_shared`, `hibob_upload_employee_avatar`, `hibob_upload_file_to_confidential_folder`, `hibob_upload_file_to_custom_folder`, `hibob_upload_file_to_shared_folder` `auth` Restored the Service User authentication option alongside OAuth 2.0, for customers who manage their own service user credentials. `hibob_add_item_to_list`, `hibob_add_policy_type_reason_codes`, `hibob_adjust_time_off_balance`, `hibob_cancel_position`, `hibob_cancel_time_off_request`, `hibob_create_bank_account`, `hibob_create_custom_field`, `hibob_create_employee`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_position_opening`, `hibob_create_salary_entry`, `hibob_create_time_off_request`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_create_work_history_entry`, `hibob_delete_bank_account`, `hibob_delete_custom_field`, `hibob_delete_document_from_confidential_folder`, `hibob_delete_document_from_custom_folder`, `hibob_delete_document_from_shared_folder`, `hibob_delete_employment_entry`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_key_result`, `hibob_delete_list_item`, `hibob_delete_position_opening`, `hibob_delete_salary_entry`, `hibob_delete_training_record`, `hibob_delete_variable_payment`, `hibob_delete_work_history_entry`, `hibob_get_all_company_lists`, `hibob_get_all_fields`, `hibob_get_all_policy_types`, `hibob_get_avatar_by_email`, `hibob_get_company_list_by_name`, `hibob_get_company_reports`, `hibob_get_document_folders_metadata`, `hibob_get_employee`, `hibob_get_employee_avatar`, `hibob_get_employee_time_off_balance`, `hibob_get_goal_type_metadata`, `hibob_get_goals_metadata`, `hibob_get_job_ad`, `hibob_get_job_families`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles`, `hibob_get_job_roles_metadata`, `hibob_get_key_results_metadata`, `hibob_get_onboarding_wizards`, `hibob_get_payroll_history`, `hibob_get_policy_details`, `hibob_get_policy_names`, `hibob_get_policy_type_details`, `hibob_get_policy_type_reason_codes`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_get_report_download_url`, `hibob_get_time_off_changes`, `hibob_get_time_off_request`, `hibob_get_whos_out`, `hibob_get_whos_out_today`, `hibob_import_attendance_data`, `hibob_invite_employee`, `hibob_list_all_open_tasks`, `hibob_list_bulk_employment_history`, `hibob_list_bulk_lifecycle_history`, `hibob_list_bulk_salaries_history`, `hibob_list_bulk_work_history`, `hibob_list_employee_bank_accounts`, `hibob_list_employee_documents`, `hibob_list_employee_employment_history`, `hibob_list_employee_equity_grants`, `hibob_list_employee_lifecycle_history`, `hibob_list_employee_salary_history`, `hibob_list_employee_tasks`, `hibob_list_employee_training_records`, `hibob_list_employee_variable_payments`, `hibob_list_employee_work_history`, `hibob_mark_task_complete`, `hibob_search_actual_payments`, `hibob_search_employees`, `hibob_search_goal_types`, `hibob_search_goals`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_key_results`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_terminate_employee`, `hibob_uninvite_employee`, `hibob_update_bank_account`, `hibob_update_custom_field`, `hibob_update_employee`, `hibob_update_employee_email`, `hibob_update_employee_start_date`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_key_results_progress`, `hibob_update_list_item`, `hibob_update_position`, `hibob_update_position_budget`, `hibob_update_position_opening`, `hibob_update_work_history_entry`, `hibob_upload_document_from_url_to_confidential`, `hibob_upload_document_from_url_to_custom_folder`, `hibob_upload_document_from_url_to_shared`, `hibob_upload_employee_avatar`, `hibob_upload_file_to_confidential_folder`, `hibob_upload_file_to_custom_folder`, `hibob_upload_file_to_shared_folder` `auth` `breaking-changes` Migrated from requiredScopes to authRequirements for per-auth-type scope control. `hibob_add_item_to_list`, `hibob_add_policy_type_reason_codes`, `hibob_adjust_time_off_balance`, `hibob_cancel_position`, `hibob_cancel_time_off_request`, `hibob_create_bank_account`, `hibob_create_custom_field`, `hibob_create_employee`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_position_opening`, `hibob_create_salary_entry`, `hibob_create_time_off_request`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_create_work_history_entry`, `hibob_delete_bank_account`, `hibob_delete_custom_field`, `hibob_delete_document_from_confidential_folder`, `hibob_delete_document_from_custom_folder`, `hibob_delete_document_from_shared_folder`, `hibob_delete_employment_entry`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_key_result`, `hibob_delete_list_item`, `hibob_delete_position_opening`, `hibob_delete_salary_entry`, `hibob_delete_training_record`, `hibob_delete_variable_payment`, `hibob_delete_work_history_entry`, `hibob_get_all_company_lists`, `hibob_get_all_fields`, `hibob_get_all_policy_types`, `hibob_get_avatar_by_email`, `hibob_get_company_list_by_name`, `hibob_get_company_reports`, `hibob_get_document_folders_metadata`, `hibob_get_employee`, `hibob_get_employee_avatar`, `hibob_get_employee_time_off_balance`, `hibob_get_goal_type_metadata`, `hibob_get_goals_metadata`, `hibob_get_job_ad`, `hibob_get_job_families`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles`, `hibob_get_job_roles_metadata`, `hibob_get_key_results_metadata`, `hibob_get_onboarding_wizards`, `hibob_get_payroll_history`, `hibob_get_policy_details`, `hibob_get_policy_names`, `hibob_get_policy_type_details`, `hibob_get_policy_type_reason_codes`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_get_report_download_url`, `hibob_get_time_off_changes`, `hibob_get_time_off_request`, `hibob_get_whos_out`, `hibob_get_whos_out_today`, `hibob_import_attendance_data`, `hibob_invite_employee`, `hibob_list_all_open_tasks`, `hibob_list_bulk_employment_history`, `hibob_list_bulk_lifecycle_history`, `hibob_list_bulk_salaries_history`, `hibob_list_bulk_work_history`, `hibob_list_employee_bank_accounts`, `hibob_list_employee_documents`, `hibob_list_employee_employment_history`, `hibob_list_employee_equity_grants`, `hibob_list_employee_lifecycle_history`, `hibob_list_employee_salary_history`, `hibob_list_employee_tasks`, `hibob_list_employee_training_records`, `hibob_list_employee_variable_payments`, `hibob_list_employee_work_history`, `hibob_mark_task_complete`, `hibob_search_actual_payments`, `hibob_search_employees`, `hibob_search_goal_types`, `hibob_search_goals`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_key_results`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_terminate_employee`, `hibob_uninvite_employee`, `hibob_update_bank_account`, `hibob_update_custom_field`, `hibob_update_employee`, `hibob_update_employee_email`, `hibob_update_employee_start_date`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_key_results_progress`, `hibob_update_list_item`, `hibob_update_position`, `hibob_update_position_budget`, `hibob_update_position_opening`, `hibob_update_work_history_entry`, `hibob_upload_document_from_url_to_confidential`, `hibob_upload_document_from_url_to_custom_folder`, `hibob_upload_document_from_url_to_shared`, `hibob_upload_employee_avatar`, `hibob_upload_file_to_confidential_folder`, `hibob_upload_file_to_custom_folder`, `hibob_upload_file_to_shared_folder` `new-feature` Enabled Data Sync on 13 list actions covering the full employee dataset, company fields, open tasks, reports, document folders, onboarding wizards and job catalog and workforce planning metadata. Synced collections can be searched and filtered without consuming HiBob API quota. `hibob_get_all_fields`, `hibob_get_company_reports`, `hibob_get_document_folders_metadata`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles_metadata`, `hibob_get_onboarding_wizards`, `hibob_get_payroll_history`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_list_all_open_tasks` `fix` `action-descriptions` Fixed payFrequency and variableType fields from hardcoded enums to company-list-based strings. Corrected contract value format (space not hyphen). Documented mandatory filter requirement for position search actions. Made effectiveDate required on adjust_time_off_balance. `hibob_adjust_time_off_balance`, `hibob_create_employment_history_entry`, `hibob_create_salary_entry`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_update_employment_entry` `fix` Marked search_goals action as preview due to Talent API Module subscription requirement. `hibob_search_goals` `downstream-change` `auth` Remove the Service User authentication option. OAuth 2.0 is now the only supported authentication method, per HiBob's requirement that integrations authenticate via OAuth. `hibob_add_item_to_list`, `hibob_add_policy_type_reason_codes`, `hibob_adjust_time_off_balance`, `hibob_cancel_position`, `hibob_cancel_time_off_request`, `hibob_create_bank_account`, `hibob_create_custom_field`, `hibob_create_employee`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_position_opening`, `hibob_create_salary_entry`, `hibob_create_time_off_request`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_create_work_history_entry`, `hibob_delete_bank_account`, `hibob_delete_custom_field`, `hibob_delete_document_from_confidential_folder`, `hibob_delete_document_from_custom_folder`, `hibob_delete_document_from_shared_folder`, `hibob_delete_employment_entry`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_key_result`, `hibob_delete_list_item`, `hibob_delete_position_opening`, `hibob_delete_salary_entry`, `hibob_delete_training_record`, `hibob_delete_variable_payment`, `hibob_delete_work_history_entry`, `hibob_get_all_company_lists`, `hibob_get_all_fields`, `hibob_get_all_policy_types`, `hibob_get_avatar_by_email`, `hibob_get_company_list_by_name`, `hibob_get_company_reports`, `hibob_get_document_folders_metadata`, `hibob_get_employee`, `hibob_get_employee_avatar`, `hibob_get_employee_time_off_balance`, `hibob_get_goal_type_metadata`, `hibob_get_goals_metadata`, `hibob_get_job_ad`, `hibob_get_job_families`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles`, `hibob_get_job_roles_metadata`, `hibob_get_key_results_metadata`, `hibob_get_onboarding_wizards`, `hibob_get_payroll_history`, `hibob_get_policy_details`, `hibob_get_policy_names`, `hibob_get_policy_type_details`, `hibob_get_policy_type_reason_codes`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_get_report_download_url`, `hibob_get_time_off_changes`, `hibob_get_time_off_request`, `hibob_get_whos_out`, `hibob_get_whos_out_today`, `hibob_import_attendance_data`, `hibob_invite_employee`, `hibob_list_all_open_tasks`, `hibob_list_bulk_employment_history`, `hibob_list_bulk_lifecycle_history`, `hibob_list_bulk_salaries_history`, `hibob_list_bulk_work_history`, `hibob_list_employee_bank_accounts`, `hibob_list_employee_documents`, `hibob_list_employee_employment_history`, `hibob_list_employee_equity_grants`, `hibob_list_employee_lifecycle_history`, `hibob_list_employee_salary_history`, `hibob_list_employee_tasks`, `hibob_list_employee_training_records`, `hibob_list_employee_variable_payments`, `hibob_list_employee_work_history`, `hibob_mark_task_complete`, `hibob_search_actual_payments`, `hibob_search_employees`, `hibob_search_goal_types`, `hibob_search_goals`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_key_results`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_terminate_employee`, `hibob_uninvite_employee`, `hibob_update_bank_account`, `hibob_update_custom_field`, `hibob_update_employee`, `hibob_update_employee_email`, `hibob_update_employee_start_date`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_key_results_progress`, `hibob_update_list_item`, `hibob_update_position`, `hibob_update_position_budget`, `hibob_update_position_opening`, `hibob_update_work_history_entry`, `hibob_upload_document_from_url_to_confidential`, `hibob_upload_document_from_url_to_custom_folder`, `hibob_upload_document_from_url_to_shared`, `hibob_upload_employee_avatar`, `hibob_upload_file_to_confidential_folder`, `hibob_upload_file_to_custom_folder`, `hibob_upload_file_to_shared_folder` `downstream-change` `auth` Send partner-attribution headers on all API calls, with X-Global-Partner-Id for OAuth connections and Partner-token for Service User connections. `hibob_add_item_to_list`, `hibob_add_policy_type_reason_codes`, `hibob_adjust_time_off_balance`, `hibob_cancel_position`, `hibob_cancel_time_off_request`, `hibob_create_bank_account`, `hibob_create_custom_field`, `hibob_create_employee`, `hibob_create_employment_history_entry`, `hibob_create_equity_grant`, `hibob_create_goals`, `hibob_create_key_results`, `hibob_create_position`, `hibob_create_position_budget`, `hibob_create_position_opening`, `hibob_create_salary_entry`, `hibob_create_time_off_request`, `hibob_create_training_record`, `hibob_create_variable_payment`, `hibob_create_work_history_entry`, `hibob_delete_bank_account`, `hibob_delete_custom_field`, `hibob_delete_document_from_confidential_folder`, `hibob_delete_document_from_custom_folder`, `hibob_delete_document_from_shared_folder`, `hibob_delete_employment_entry`, `hibob_delete_equity_grant`, `hibob_delete_goal`, `hibob_delete_key_result`, `hibob_delete_list_item`, `hibob_delete_position_opening`, `hibob_delete_salary_entry`, `hibob_delete_training_record`, `hibob_delete_variable_payment`, `hibob_delete_work_history_entry`, `hibob_get_all_company_lists`, `hibob_get_all_fields`, `hibob_get_all_policy_types`, `hibob_get_avatar_by_email`, `hibob_get_company_list_by_name`, `hibob_get_company_reports`, `hibob_get_document_folders_metadata`, `hibob_get_employee`, `hibob_get_employee_avatar`, `hibob_get_employee_time_off_balance`, `hibob_get_goal_type_metadata`, `hibob_get_goals_metadata`, `hibob_get_job_ad`, `hibob_get_job_families`, `hibob_get_job_families_metadata`, `hibob_get_job_family_groups`, `hibob_get_job_family_groups_metadata`, `hibob_get_job_profiles_metadata`, `hibob_get_job_roles`, `hibob_get_job_roles_metadata`, `hibob_get_key_results_metadata`, `hibob_get_onboarding_wizards`, `hibob_get_payroll_history`, `hibob_get_policy_details`, `hibob_get_policy_names`, `hibob_get_policy_type_details`, `hibob_get_policy_type_reason_codes`, `hibob_get_position_budget_metadata`, `hibob_get_position_openings_metadata`, `hibob_get_positions_metadata`, `hibob_get_report_download_url`, `hibob_get_time_off_changes`, `hibob_get_time_off_request`, `hibob_get_whos_out`, `hibob_get_whos_out_today`, `hibob_import_attendance_data`, `hibob_invite_employee`, `hibob_list_all_open_tasks`, `hibob_list_bulk_employment_history`, `hibob_list_bulk_lifecycle_history`, `hibob_list_bulk_salaries_history`, `hibob_list_bulk_work_history`, `hibob_list_employee_bank_accounts`, `hibob_list_employee_documents`, `hibob_list_employee_employment_history`, `hibob_list_employee_equity_grants`, `hibob_list_employee_lifecycle_history`, `hibob_list_employee_salary_history`, `hibob_list_employee_tasks`, `hibob_list_employee_training_records`, `hibob_list_employee_variable_payments`, `hibob_list_employee_work_history`, `hibob_mark_task_complete`, `hibob_search_actual_payments`, `hibob_search_employees`, `hibob_search_goal_types`, `hibob_search_goals`, `hibob_search_job_ads`, `hibob_search_job_profiles`, `hibob_search_key_results`, `hibob_search_position_budgets`, `hibob_search_position_openings`, `hibob_search_positions`, `hibob_terminate_employee`, `hibob_uninvite_employee`, `hibob_update_bank_account`, `hibob_update_custom_field`, `hibob_update_employee`, `hibob_update_employee_email`, `hibob_update_employee_start_date`, `hibob_update_employment_entry`, `hibob_update_equity_grant`, `hibob_update_goal`, `hibob_update_goal_status`, `hibob_update_key_results_details`, `hibob_update_key_results_progress`, `hibob_update_list_item`, `hibob_update_position`, `hibob_update_position_budget`, `hibob_update_position_opening`, `hibob_update_work_history_entry`, `hibob_upload_document_from_url_to_confidential`, `hibob_upload_document_from_url_to_custom_folder`, `hibob_upload_document_from_url_to_shared`, `hibob_upload_employee_avatar`, `hibob_upload_file_to_confidential_folder`, `hibob_upload_file_to_custom_folder`, `hibob_upload_file_to_shared_folder` `guide-improvement` Improved guide visibility for environment selection — extracted inline bullet into dedicated "Sandbox vs Production Environment" section with sub-steps. # HighLevel Source: https://docs.stackone.com/connectors/highlevel/index How to set up the HighLevel connector, plus the actions that are available.

Previewv0.1.0

See changelog

12 actions · 2 auth methods

CRM IAM

v1.1.0

See changelog

3 actions · 1 auth method

ATS

v2.2.1

See changelog

29 actions · 7 events · 1 auth method

Project Management IAM

Betav1.1.0

See changelog

11 actions · 1 auth method

ATS

v2.2.0

See changelog

79 actions · 8 events · 2 auth methods

Observability

Previewv1.3.0

See changelog

52 actions · 1 auth method

IAM

Betav1.0.0

4 actions · 1 auth method

Surveys

Previewv2.0.0

See changelog

64 actions · 1 auth method

HRIS

v1.1.0

See changelog

48 actions · 1 auth method

HRIS

v3.2.1

See changelog

90 actions · 2 auth methods

CRM IAM Customer Support

Previewv0.1.0

See changelog

126 actions · 2 auth methods

AI Productivity Developer Tools IAM Storage Billing

v1.1.0

See changelog

117 actions · 1 auth method

HRIS

Betav0.2.0

See changelog

174 actions · 1 auth method

Observability

Previewv1.2.0

See changelog

34 actions · 1 auth method

LMS

v1.0.0

2 actions · 1 auth method

E-Commerce

Previewv2.0.0

See changelog

74 actions · 2 events · 1 auth method

CRM

Previewv1.1.0

See changelog

53 actions · 2 auth methods

Marketing IAM

Betav0.2.0

See changelog

76 actions · 1 auth method

HRIS

v2.0.2

See changelog

113 actions · 117 events · 2 auth methods

Customer Support Ticketing

v1.1.0

See changelog

64 actions · 1 auth method

Previewv0.1.0

See changelog

18 actions · 1 auth method

Infrastructure IAM

v1.0.0

See changelog

14 actions · 1 auth method

Developer Tools Security Localization

Betav1.1.0

See changelog

64 actions · 12 events · 2 auth methods

Contract Lifecycle Management

v1.2.0

See changelog

68 actions · 36 events · 1 auth method

Marketing

v1.3.0

See changelog

62 actions · 2 auth methods

Device Management IAM

Betav1.1.0

See changelog

26 actions · 1 auth method

ATS

Betav0.2.0

See changelog

15 actions · 1 auth method

ERP

Previewv0.1.0

See changelog

6 actions · 1 auth method

IAM Developer Tools

v1.0.0

See changelog

58 actions · 11 events · 1 auth method

Project Management

v1.1.0

See changelog

147 actions · 47 events · 2 auth methods

Project Management IAM

v1.2.0

See changelog

42 actions · 17 events · 2 auth methods

ITSM Ticketing

v2.0.0

See changelog

247 actions · 43 events · 1 auth method

ATS

Betav1.1.0

See changelog

41 actions · 1 auth method

ATS

Betav1.1.0

See changelog

40 actions · 1 auth method

ATS

v1.2.0

See changelog

6 actions · 1 auth method

ATS

Previewv1.1.0

See changelog

23 actions · 1 auth method

ATS

Previewv1.1.1

See changelog

44 actions · 1 auth method

Surveys

Betav0.2.1

See changelog

59 actions · 1 auth method

ATS Marketing

Previewv1.4.4

See changelog

78 actions · 1 event · 2 auth methods

IAM Device Management

Betav0.1.0

See changelog

55 actions · 1 auth method

Security Observability IAM

Previewv1.2.0

See changelog

88 actions · 24 events · 1 auth method

Telephony Scheduling CRM IAM Messaging

Betav1.1.0

See changelog

21 actions · 1 auth method

HRIS

v2.1.0

See changelog

37 actions · 1 auth method

Analytics

Betav1.1.0

See changelog

158 actions · 34 events · 2 auth methods

CRM

Previewv0.1.0

See changelog

9 actions · 1 auth method

IAM

Betav1.1.0

See changelog

75 actions · 2 auth methods

HRIS ATS

Betav1.1.0

See changelog

63 actions · 1 auth method

HRIS

v1.2.0

See changelog

57 actions · 24 events · 1 auth method

Marketing

v1.1.0

See changelog

44 actions · 1 auth method

HRIS

v1.4.0

See changelog

172 actions · 25 events · 2 auth methods

Marketing IAM

Betav1.1.0

See changelog

53 actions · 2 auth methods

Customer Support Ticketing

Betav1.1.0

See changelog

56 actions · 1 auth method

Security

Previewv0.3.0

See changelog

47 actions · 1 auth method

Translation

v1.1.2

See changelog

34 actions · 1 auth method

IAM

v1.1.0

See changelog

34 actions · 1 auth method

HRIS

v1.0.0

26 actions · 1 auth method

HRIS

v4.2.1

See changelog

96 actions · 41 events · 1 auth method

Developer Tools IAM

Betav1.1.0

See changelog

26 actions · 1 auth method

CRM

Betav1.1.0

See changelog

29 actions · 2 auth methods

HRIS IAM

v2.4.0

See changelog

76 actions · 10 events · 1 auth method

Marketing IAM

v2.1.0

See changelog

77 actions · 10 events · 1 auth method

ATS

v1.2.0

See changelog

104 actions · 10 events · 2 auth methods

CMS IAM

Previewv1.1.0

See changelog

57 actions · 8 events · 1 auth method

E-Commerce

Betav0.2.1

See changelog

58 actions · 1 auth method

Localization AI

v2.1.0

See changelog

138 actions · 43 events · 2 auth methods

Project Management IAM

Previewv1.0.0

2 actions · 2 auth methods

Messaging IAM

Previewv1.0.0

7 actions · 1 auth method

LMS

v1.1.0

See changelog

27 actions · 1 auth method

ATS

v1.3.0

See changelog

111 actions · 33 events · 1 auth method

Translation IAM

Betav1.1.0

See changelog

61 actions · 1 auth method

HRIS

Previewv0.2.0

See changelog

7 actions · 1 auth method

IAM Media

Betav3.3.0

See changelog

49 actions · 12 events · 2 auth methods

HRIS

Betav1.0.0

See changelog

60 actions · 2 auth methods

IAM Documents Storage

Betav0.2.0

See changelog

37 actions · 1 auth method

Analytics

Previewv1.1.1

See changelog

40 actions · 1 auth method

CRM

Previewv1.0.0

128 actions · 1 auth method

E-Commerce

Betav1.0.0

See changelog

15 actions · 1 auth method

Vendor Management System

Betav0.1.0

See changelog

32 actions · 1 auth method

Vendor Management System

v1.2.0

See changelog

91 actions · 7 events · 2 auth methods

Marketing

v1.1.1

See changelog

51 actions · 12 events · 1 auth method

Marketing

v1.3.0

See changelog

96 actions · 9 events · 1 auth method

Messaging IAM

v1.2.0

See changelog

59 actions · 8 events · 1 auth method

Messaging

Previewv2.1.0

See changelog

70 actions · 1 event · 1 auth method

IAM

Betav2.2.0

See changelog

132 actions · 1 auth method

ATS IAM

v1.1.0

See changelog

71 actions · 1 auth method

Developer Tools AI IAM Billing Observability

Betav1.1.0

See changelog

59 actions · 1 auth method

Marketing

v1.2.0

See changelog

40 actions · 6 events · 1 auth method

Data Integration

Betav1.0.0

5 actions · 1 auth method

Marketing

Previewv1.0.0

56 actions · 2 auth methods

Project Management

v1.1.0

See changelog

47 actions · 1 auth method

ATS

Previewv0.1.1

See changelog

14 actions · 1 auth method

Analytics IAM

v3.0.0

See changelog

70 actions · 64 events · 1 auth method

ERP

Previewv1.2.0

See changelog

68 actions · 6 events · 2 auth methods

IAM

Previewv1.2.0

See changelog

102 actions · 1 auth method

Productivity

v1.1.0

See changelog

43 actions · 2 auth methods

Device Management

v1.1.0

See changelog

46 actions · 1 auth method

Storage Documents IAM

v2.2.0

See changelog

39 actions · 5 events · 1 auth method

Messaging

v2.2.0

See changelog

72 actions · 15 events · 3 auth methods

IAM Messaging

Previewv2.1.3

See changelog

16 actions · 2 auth methods

Knowledge Management Analytics

v3.1.1

See changelog

95 actions · 2 auth methods

Design IAM

v1.2.1

See changelog

68 actions · 1 auth method

AI IAM

v2.4.0

See changelog

54 actions · 4 events · 1 auth method

Analytics IAM

Previewv1.3.1

See changelog

44 actions · 1 auth method

Marketing

Previewv1.1.2

See changelog

110 actions · 1 auth method

Project Management IAM

v1.3.0

See changelog

68 actions · 62 events · 2 auth methods

Accounting

v1.3.0

See changelog

71 actions · 2 events · 1 auth method

Databases Observability IAM

Betav1.1.0

See changelog

30 actions · 1 auth method

Expense Management

Betav1.1.0

See changelog

43 actions · 1 auth method

Knowledge Management

v1.0.0

54 actions · 1 auth method

MCP

Betav1.1.0

See changelog

54 actions · 2 auth methods

HRIS

v1.1.0

See changelog

29 actions · 1 auth method

v1.1.0

See changelog

67 actions · 1 auth method

Weather

v1.3.0

See changelog

42 actions · 21 events · 1 auth method

Developer Tools IAM

v1.6.0

See changelog

80 actions · 2 auth methods

ERP IAM

Previewv1.3.0

See changelog

135 actions · 6 events · 1 auth method

Observability IAM

Betav1.3.1

See changelog

105 actions · 2 auth methods

Device Management IAM

Previewv2.0.0

See changelog

70 actions · 1 event · 1 auth method

HRIS

v1.2.0

See changelog

35 actions · 9 events · 3 auth methods

Knowledge Management IAM

v1.4.0

See changelog

75 actions · 26 events · 1 auth method

CRM

Betav0.2.0

See changelog

71 actions · 2 auth methods

HRIS

v3.3.1

See changelog

115 actions · 21 events · 3 auth methods

IAM

v1.3.1

See changelog

98 actions · 45 events · 1 auth method

E-Signature

Previewv1.2.0

See changelog

119 actions · 1 auth method

IAM

Previewv1.1.0

See changelog

37 actions · 1 auth method

Productivity IAM

v1.1.1

See changelog

63 actions · 24 events · 1 auth method

Developer Tools Marketing Messaging

Betav0.2.0

See changelog

70 actions · 1 auth method

Legal Contract Lifecycle Management

v1.0.0

See changelog

25 actions · 2 auth methods

Previewv1.0.0

6 actions · 2 auth methods

Weather

v1.2.3

See changelog

121 actions · 16 events · 3 auth methods

AI IAM

Previewv0.1.0

See changelog

69 actions · 4 auth methods

Developer Tools

v2.1.0

See changelog

85 actions · 2 auth methods

Previewv2.0.0

See changelog

68 actions · 1 auth method

Security IAM

Previewv0.2.0

See changelog

16 actions · 3 auth methods

LMS

Previewv0.2.0

See changelog

120 actions · 3 auth methods

HRIS

v1.2.0

See changelog

42 actions · 15 events · 1 auth method

E-Commerce

v1.2.0

See changelog

77 actions · 5 events · 1 auth method

Scheduling IAM

Betav0.3.0

See changelog

253 actions · 1 auth method

CRM IAM Developer Tools

v1.0.0

See changelog

7 actions · 1 auth method

Developer Tools

v1.1.0

See changelog

59 actions · 45 events · 1 auth method

HRIS

v1.3.0

See changelog

54 actions · 57 events · 1 auth method

Payments

v1.4.0

See changelog

50 actions · 31 events · 1 auth method

ITSM Ticketing IAM

v1.2.0

See changelog

29 actions · 11 events · 1 auth method

Previewv2.0.1

See changelog

88 actions · 1 auth method

Marketing

Betav1.1.0

See changelog

41 actions · 13 events · 1 auth method

HRIS

Betav1.1.0

See changelog

38 actions · 49 events · 1 auth method

HRIS

v1.1.0

See changelog

23 actions · 1 auth method

HRIS

v2.1.1

See changelog

49 actions · 5 events · 1 auth method

HRIS

v1.3.0

See changelog

64 actions · 51 events · 1 auth method

Payments IAM

Betav0.1.0

See changelog

36 actions · 1 auth method

Previewv1.1.0

See changelog

54 actions · 1 auth method

LMS

Betav1.1.0

See changelog

58 actions · 1 auth method

HRIS

Previewv1.1.1

See changelog

11 actions · 1 auth method

v1.2.0

See changelog

54 actions · 21 events · 1 auth method

HRIS ATS

Betav1.1.0

See changelog

87 actions · 1 auth method

ATS HRIS IAM

Betav0.1.0

See changelog

35 actions · 1 auth method

Previewv1.4.0

See changelog

124 actions · 42 events · 1 auth method

IAM

v1.1.0

See changelog

91 actions · 1 auth method

ATS

v1.3.1

See changelog

132 actions · 11 events · 2 auth methods

CRM IAM

v1.2.1

See changelog

59 actions · 112 events · 1 auth method

CRM

Previewv2.0.1

See changelog

59 actions · 2 auth methods

Payments

Previewv3.1.1

See changelog

77 actions · 1 auth method

HRIS

v1.2.0

See changelog

27 actions · 2 events · 1 auth method

ATS

v6.0.0

See changelog

100 actions · 10 events · 1 auth method

Analytics IAM

v1.1.4

See changelog

76 actions · 7 events · 1 auth method

Messaging

Betav1.1.0

See changelog

30 actions · 1 auth method

HRIS

v1.2.0

See changelog

24 actions · 7 events · 1 auth method

CMS

Betav0.2.1

See changelog

8 actions · 1 auth method

Payments

Betav0.2.0

See changelog

52 actions · 1 auth method

Accounting Procurement Payments IAM

Betav1.1.0

See changelog

88 actions · 1 auth method

HRIS

v1.0.0

See changelog

9 actions · 2 auth methods

Healthcare

Previewv3.0.0

See changelog

50 actions · 2 auth methods

Observability

Previewv1.2.0

See changelog

63 actions · 1 auth method

Customer Support Ticketing IAM

v2.2.0

See changelog

112 actions · 20 events · 2 auth methods

Analytics IAM

Betav0.2.0

See changelog

35 actions · 1 auth method

v1.5.0

See changelog

95 actions · 1 event · 1 auth method

Accounting

v2.0.0

See changelog

72 actions · 18 events · 1 auth method

Project Management

v1.3.1

See changelog

75 actions · 42 events · 1 auth method

Expense Management

v1.1.1

See changelog

13 actions · 1 auth method

Project Management

v2.3.1

See changelog

39 actions · 1 auth method

Customer Support Ticketing

Previewv1.1.0

See changelog

66 actions · 2 events · 1 auth method

ATS

Betav0.2.1

See changelog

83 actions · 1 auth method

ATS

v1.0.0

26 actions · 1 auth method

ATS

Betav1.0.0

49 actions · 1 auth method

ATS CRM

Previewv2.0.2

See changelog

139 actions · 1 auth method

Billing

Betav1.1.0

See changelog

57 actions · 2 auth methods

v2.1.1

See changelog

68 actions · 50 events · 1 auth method

HRIS

v1.2.0

See changelog

98 actions · 63 events · 1 auth method

Infrastructure IAM

Betav1.2.0

See changelog

13 actions · 1 auth method

Marketing

Previewv0.3.2

See changelog

38 actions · 20 events · 2 auth methods

Previewv1.3.0

See changelog

55 actions · 1 event · 1 auth method

Developer Tools IAM

v1.0.0

See changelog

2 actions · 1 auth method

Betav0.2.0

See changelog

83 actions · 1 auth method

Accounting

Betav0.3.0

See changelog

87 actions · 2 auth methods

Telephony Messaging IAM

Previewv1.1.0

See changelog

37 actions · 1 auth method

HRIS IAM

v1.2.0

See changelog

25 actions · 8 events · 1 auth method

Observability

v1.1.0

See changelog

24 actions · 1 auth method

Ticketing

Previewv1.3.0

See changelog

122 actions · 10 events · 1 auth method

LMS

v1.1.0

See changelog

35 actions · 1 auth method

HRIS

Betav1.0.1

See changelog

8 actions · 2 auth methods

HRIS

v1.3.1

See changelog

380 actions · 15 events · 1 auth method

CRM Customer Support Ticketing IAM

## Getting Started Set up a new project or select an existing one. See [Organizations & Projects](/gateway/concepts/organizations-and-projects). Enable the connector and set up a Connector Profile in your project. See [Setup Connector Profile](/gateway/quickstart#setup-connector-profile). Requires creating an External Client App in your Salesforce org. Uses PKCE and supports refresh token rotation. Optionally, configure receiving Events for Salesforce into StackOne. Link an account [from the dashboard](/connect/managing-connectors/linking-accounts#link-from-the-dashboard) (or via [StackOne Hub](/embed/account-linking/overview)). See the guide for the authentication type chosen in the Connector Profile: Connect an AI platform to the linked account's actions. See [AI Platforms](/connect/ai-platforms/overview). Other ways to call actions are listed in [Protocols & SDKs](/connect/protocols-and-sdks). ## Actions See https://docs.stackone.com/connectors/salesforce/index.md for the full list. ## Events See https://docs.stackone.com/connectors/salesforce/index.md for the full list. # Salesforce Changelog Source: https://docs.stackone.com/connectors/salesforce/changelog Release history for the Salesforce connector. Each version lists what changed and which actions were affected. Back to the connector overview, authentication methods, and actions. `bug-fix` Connections now work when a custom scope list leaves out refresh_token, and the setup guide explains Salesforce's Allow Access screen. `salesforce_abort_bulk_ingest_job`, `salesforce_abort_bulk_query_job`, `salesforce_activate_contract`, `salesforce_activate_order`, `salesforce_add_campaign_member`, `salesforce_add_group_member`, `salesforce_assign_permission_set`, `salesforce_assign_resource_to_appointment`, `salesforce_assign_topic_to_record`, `salesforce_complete_task`, `salesforce_composite_batch`, `salesforce_composite_graph`, `salesforce_create_account`, `salesforce_create_account_contact_role`, `salesforce_create_asset`, `salesforce_create_attachment`, `salesforce_create_bulk_ingest_job`, `salesforce_create_bulk_query_job`, `salesforce_create_campaign_member`, `salesforce_create_case`, `salesforce_create_case_comment`, `salesforce_create_contact`, `salesforce_create_contract`, `salesforce_create_email_message`, `salesforce_create_entitlement`, `salesforce_create_event`, `salesforce_create_feed_comment`, `salesforce_create_feed_item`, `salesforce_create_individual`, `salesforce_create_lead`, `salesforce_create_location`, `salesforce_create_note`, `salesforce_create_opportunity`, `salesforce_create_opportunity_contact_role`, `salesforce_create_opportunity_line_item`, `salesforce_create_order`, `salesforce_create_order_item`, `salesforce_create_partner`, `salesforce_create_pricebook`, `salesforce_create_pricebook_entry`, `salesforce_create_product`, `salesforce_create_return_order`, `salesforce_create_service_appointment`, `salesforce_create_service_contract`, `salesforce_create_service_resource`, `salesforce_create_solution`, `salesforce_create_task`, `salesforce_create_topic`, `salesforce_create_work_order`, `salesforce_create_work_order_line_item`, `salesforce_delete_account`, `salesforce_delete_account_contact_role`, `salesforce_delete_asset`, `salesforce_delete_attachment`, `salesforce_delete_bulk_ingest_job`, `salesforce_delete_bulk_query_job`, `salesforce_delete_campaign_member`, `salesforce_delete_case`, `salesforce_delete_case_comment`, `salesforce_delete_contact`, `salesforce_delete_content_document`, `salesforce_delete_content_document_link`, `salesforce_delete_contract`, `salesforce_delete_document`, `salesforce_delete_email_message`, `salesforce_delete_entitlement`, `salesforce_delete_event`, `salesforce_delete_feed_comment`, `salesforce_delete_feed_element`, `salesforce_delete_feed_item`, `salesforce_delete_individual`, `salesforce_delete_lead`, `salesforce_delete_location`, `salesforce_delete_note`, `salesforce_delete_opportunity`, `salesforce_delete_opportunity_contact_role`, `salesforce_delete_opportunity_line_item`, `salesforce_delete_order`, `salesforce_delete_order_item`, `salesforce_delete_partner`, `salesforce_delete_pricebook`, `salesforce_delete_pricebook_entry`, `salesforce_delete_product`, `salesforce_delete_return_order`, `salesforce_delete_service_contract`, `salesforce_delete_solution`, `salesforce_delete_task`, `salesforce_delete_topic`, `salesforce_delete_work_order`, `salesforce_describe_dashboard`, `salesforce_describe_global`, `salesforce_describe_quick_action`, `salesforce_describe_sobject`, `salesforce_download_attachment`, `salesforce_download_content_version`, `salesforce_download_document`, `salesforce_execute_composite_request`, `salesforce_execute_soql_query`, `salesforce_execute_sosl_search`, `salesforce_get_account`, `salesforce_get_account_history`, `salesforce_get_activity_history`, `salesforce_get_api_limits`, `salesforce_get_api_versions`, `salesforce_get_approval_layout`, `salesforce_get_approval_processes`, `salesforce_get_asset`, `salesforce_get_asset_hierarchy`, `salesforce_get_attachment`, `salesforce_get_bulk_ingest_job`, `salesforce_get_bulk_job_failed_results`, `salesforce_get_bulk_job_successful_results`, `salesforce_get_bulk_job_unprocessed_records`, `salesforce_get_bulk_query_job`, `salesforce_get_bulk_query_results`, `salesforce_get_business_hours`, `salesforce_get_campaign`, `salesforce_get_campaign_member`, `salesforce_get_campaign_statistics`, `salesforce_get_case`, `salesforce_get_case_comment`, `salesforce_get_case_history`, `salesforce_get_compact_layouts`, `salesforce_get_contact`, `salesforce_get_contact_history`, `salesforce_get_content_note`, `salesforce_get_content_version`, `salesforce_get_contract`, `salesforce_get_contract_history`, `salesforce_get_current_user`, `salesforce_get_dashboard`, `salesforce_get_dashboard_status`, `salesforce_get_default_business_hours`, `salesforce_get_document`, `salesforce_get_email_message`, `salesforce_get_email_template`, `salesforce_get_emails_for_record`, `salesforce_get_entitlement`, `salesforce_get_event`, `salesforce_get_events_for_contact`, `salesforce_get_feed_element`, `salesforce_get_feed_item`, `salesforce_get_folder`, `salesforce_get_forecast_by_category`, `salesforce_get_global_picklist_values`, `salesforce_get_group`, `salesforce_get_group_member`, `salesforce_get_holiday`, `salesforce_get_individual`, `salesforce_get_knowledge_article`, `salesforce_get_lead`, `salesforce_get_lead_history`, `salesforce_get_location`, `salesforce_get_milestone`, `salesforce_get_my_events`, `salesforce_get_my_tasks`, `salesforce_get_note`, `salesforce_get_open_activities`, `salesforce_get_opportunity`, `salesforce_get_opportunity_field_history`, `salesforce_get_opportunity_forecast_category`, `salesforce_get_opportunity_history`, `salesforce_get_opportunity_line_item`, `salesforce_get_opportunity_products_summary`, `salesforce_get_order`, `salesforce_get_order_item`, `salesforce_get_orders_for_account`, `salesforce_get_organization_info`, `salesforce_get_overdue_tasks`, `salesforce_get_page_layouts`, `salesforce_get_partner`, `salesforce_get_pipeline_by_stage`, `salesforce_get_pricebook`, `salesforce_get_pricebook_entry`, `salesforce_get_product`, `salesforce_get_product_pricing`, `salesforce_get_profile`, `salesforce_get_queue_sobjects`, `salesforce_get_recent_activities`, `salesforce_get_recently_viewed`, `salesforce_get_record_type`, `salesforce_get_record_type_by_name`, `salesforce_get_report`, `salesforce_get_return_order`, `salesforce_get_role_hierarchy`, `salesforce_get_service_appointment`, `salesforce_get_service_contract`, `salesforce_get_service_resource`, `salesforce_get_service_territory`, `salesforce_get_solution`, `salesforce_get_standard_pricebook`, `salesforce_get_tabs`, `salesforce_get_task`, `salesforce_get_tasks_due_today`, `salesforce_get_tasks_for_contact`, `salesforce_get_themes`, `salesforce_get_topic`, `salesforce_get_topics_for_record`, `salesforce_get_upcoming_events`, `salesforce_get_user`, `salesforce_get_user_permissions`, `salesforce_get_user_role`, `salesforce_get_users_in_group`, `salesforce_get_work_order`, `salesforce_like_feed_element`, `salesforce_link_solution_to_case`, `salesforce_list_account_contact_roles`, `salesforce_list_accounts`, `salesforce_list_active_opportunity_stages`, `salesforce_list_all_groups`, `salesforce_list_apex_actions`, `salesforce_list_assets`, `salesforce_list_assigned_resources`, `salesforce_list_attachments`, `salesforce_list_authorization_form_consents`, `salesforce_list_bulk_ingest_jobs`, `salesforce_list_bulk_query_jobs`, `salesforce_list_business_hours`, `salesforce_list_campaign_member_statuses`, `salesforce_list_campaign_members`, `salesforce_list_campaigns`, `salesforce_list_case_comments`, `salesforce_list_case_milestones`, `salesforce_list_case_solutions`, `salesforce_list_case_statuses`, `salesforce_list_cases`, `salesforce_list_chatter_groups`, `salesforce_list_contact_point_consents`, `salesforce_list_contacts`, `salesforce_list_content_documents`, `salesforce_list_content_versions`, `salesforce_list_contract_statuses`, `salesforce_list_contracts`, `salesforce_list_custom_invocable_actions`, `salesforce_list_dashboards`, `salesforce_list_data_category_groups`, `salesforce_list_documents`, `salesforce_list_email_message_relations`, `salesforce_list_email_messages`, `salesforce_list_email_templates`, `salesforce_list_entitlement_processes`, `salesforce_list_entitlements`, `salesforce_list_events`, `salesforce_list_feed_comments`, `salesforce_list_feed_items`, `salesforce_list_flow_actions`, `salesforce_list_folders`, `salesforce_list_group_members`, `salesforce_list_holidays`, `salesforce_list_individuals`, `salesforce_list_knowledge_articles`, `salesforce_list_lead_statuses`, `salesforce_list_leads`, `salesforce_list_locations`, `salesforce_list_milestones`, `salesforce_list_notes`, `salesforce_list_opportunities`, `salesforce_list_opportunity_contact_roles`, `salesforce_list_opportunity_line_items`, `salesforce_list_opportunity_stages`, `salesforce_list_order_items`, `salesforce_list_order_statuses`, `salesforce_list_orders`, `salesforce_list_org_wide_email_addresses`, `salesforce_list_partners`, `salesforce_list_periods`, `salesforce_list_permission_sets`, `salesforce_list_pricebook_entries`, `salesforce_list_pricebooks`, `salesforce_list_process_instance_steps`, `salesforce_list_process_instance_work_items`, `salesforce_list_process_instances`, `salesforce_list_products`, `salesforce_list_profiles`, `salesforce_list_public_case_comments`, `salesforce_list_public_groups`, `salesforce_list_queues`, `salesforce_list_quick_actions_global`, `salesforce_list_record_types`, `salesforce_list_report_instances`, `salesforce_list_reports`, `salesforce_list_return_order_line_items`, `salesforce_list_return_orders`, `salesforce_list_service_appointments`, `salesforce_list_service_contracts`, `salesforce_list_service_resources`, `salesforce_list_service_territories`, `salesforce_list_setup_audit_trail`, `salesforce_list_sobjects`, `salesforce_list_solution_statuses`, `salesforce_list_solutions`, `salesforce_list_task_statuses`, `salesforce_list_tasks`, `salesforce_list_topic_assignments`, `salesforce_list_topics`, `salesforce_list_user_licenses`, `salesforce_list_user_roles`, `salesforce_list_users`, `salesforce_list_users_by_profile`, `salesforce_list_users_by_role`, `salesforce_list_work_order_line_items`, `salesforce_list_work_order_statuses`, `salesforce_list_work_orders`, `salesforce_parameterized_search`, `salesforce_post_comment`, `salesforce_post_feed_element`, `salesforce_recall_approval`, `salesforce_refresh_dashboard`, `salesforce_remove_group_member`, `salesforce_remove_permission_set`, `salesforce_remove_topic_from_record`, `salesforce_run_report_async`, `salesforce_run_report_sync`, `salesforce_schedule_meeting`, `salesforce_search_accounts`, `salesforce_search_assets`, `salesforce_search_campaign_members`, `salesforce_search_campaigns`, `salesforce_search_cases`, `salesforce_search_contacts`, `salesforce_search_contracts`, `salesforce_search_knowledge_articles`, `salesforce_search_leads`, `salesforce_search_locations`, `salesforce_search_opportunities`, `salesforce_search_orders`, `salesforce_search_pricebook_entries`, `salesforce_search_solutions`, `salesforce_search_suggest_records`, `salesforce_search_topics`, `salesforce_search_users`, `salesforce_search_work_orders`, `salesforce_send_email`, `salesforce_sobject_collections_create`, `salesforce_sobject_collections_delete`, `salesforce_sobject_collections_update`, `salesforce_transfer_record_ownership`, `salesforce_unified_get_group`, `salesforce_unified_get_me`, `salesforce_unified_get_organization`, `salesforce_unified_get_role`, `salesforce_unified_get_user`, `salesforce_unified_list_groups`, `salesforce_unified_list_organizations`, `salesforce_unified_list_roles`, `salesforce_unified_list_users`, `salesforce_unlink_solution_from_case`, `salesforce_update_account`, `salesforce_update_account_contact_role`, `salesforce_update_asset`, `salesforce_update_campaign_member`, `salesforce_update_case`, `salesforce_update_case_comment`, `salesforce_update_contact`, `salesforce_update_contract`, `salesforce_update_entitlement`, `salesforce_update_event`, `salesforce_update_individual`, `salesforce_update_lead`, `salesforce_update_location`, `salesforce_update_note`, `salesforce_update_opportunity`, `salesforce_update_opportunity_contact_role`, `salesforce_update_opportunity_forecast_category`, `salesforce_update_opportunity_line_item`, `salesforce_update_order`, `salesforce_update_order_item`, `salesforce_update_pricebook`, `salesforce_update_pricebook_entry`, `salesforce_update_product`, `salesforce_update_return_order`, `salesforce_update_service_appointment`, `salesforce_update_service_contract`, `salesforce_update_service_resource`, `salesforce_update_solution`, `salesforce_update_task`, `salesforce_update_topic`, `salesforce_update_user`, `salesforce_update_work_order`, `salesforce_upload_bulk_job_data` `new-feature` Create and update actions for most records, including Cases, can now set your org's custom fields and record types. `salesforce_create_account`, `salesforce_create_asset`, `salesforce_create_campaign_member`, `salesforce_create_case`, `salesforce_create_contact`, `salesforce_create_contract`, `salesforce_create_email_message`, `salesforce_create_entitlement`, `salesforce_create_event`, `salesforce_create_individual`, `salesforce_create_lead`, `salesforce_create_location`, `salesforce_create_opportunity`, `salesforce_create_opportunity_contact_role`, `salesforce_create_opportunity_line_item`, `salesforce_create_order`, `salesforce_create_order_item`, `salesforce_create_pricebook`, `salesforce_create_pricebook_entry`, `salesforce_create_product`, `salesforce_create_return_order`, `salesforce_create_service_appointment`, `salesforce_create_service_contract`, `salesforce_create_service_resource`, `salesforce_create_solution`, `salesforce_create_task`, `salesforce_create_work_order`, `salesforce_create_work_order_line_item`, `salesforce_update_account`, `salesforce_update_asset`, `salesforce_update_campaign_member`, `salesforce_update_case`, `salesforce_update_contact`, `salesforce_update_contract`, `salesforce_update_entitlement`, `salesforce_update_event`, `salesforce_update_individual`, `salesforce_update_lead`, `salesforce_update_location`, `salesforce_update_opportunity`, `salesforce_update_opportunity_contact_role`, `salesforce_update_opportunity_line_item`, `salesforce_update_order`, `salesforce_update_order_item`, `salesforce_update_pricebook`, `salesforce_update_pricebook_entry`, `salesforce_update_product`, `salesforce_update_return_order`, `salesforce_update_service_appointment`, `salesforce_update_service_contract`, `salesforce_update_service_resource`, `salesforce_update_solution`, `salesforce_update_task`, `salesforce_update_user`, `salesforce_update_work_order` `auth` Connections now use PKCE, so Salesforce apps that require it (every External Client App created on or after 9 July 2026) can connect. `salesforce_abort_bulk_ingest_job`, `salesforce_abort_bulk_query_job`, `salesforce_activate_contract`, `salesforce_activate_order`, `salesforce_add_campaign_member`, `salesforce_add_group_member`, `salesforce_assign_permission_set`, `salesforce_assign_resource_to_appointment`, `salesforce_assign_topic_to_record`, `salesforce_complete_task`, `salesforce_composite_batch`, `salesforce_composite_graph`, `salesforce_create_account`, `salesforce_create_account_contact_role`, `salesforce_create_asset`, `salesforce_create_attachment`, `salesforce_create_bulk_ingest_job`, `salesforce_create_bulk_query_job`, `salesforce_create_campaign_member`, `salesforce_create_case`, `salesforce_create_case_comment`, `salesforce_create_contact`, `salesforce_create_contract`, `salesforce_create_email_message`, `salesforce_create_entitlement`, `salesforce_create_event`, `salesforce_create_feed_comment`, `salesforce_create_feed_item`, `salesforce_create_individual`, `salesforce_create_lead`, `salesforce_create_location`, `salesforce_create_note`, `salesforce_create_opportunity`, `salesforce_create_opportunity_contact_role`, `salesforce_create_opportunity_line_item`, `salesforce_create_order`, `salesforce_create_order_item`, `salesforce_create_partner`, `salesforce_create_pricebook`, `salesforce_create_pricebook_entry`, `salesforce_create_product`, `salesforce_create_return_order`, `salesforce_create_service_appointment`, `salesforce_create_service_contract`, `salesforce_create_service_resource`, `salesforce_create_solution`, `salesforce_create_task`, `salesforce_create_topic`, `salesforce_create_work_order`, `salesforce_create_work_order_line_item`, `salesforce_delete_account`, `salesforce_delete_account_contact_role`, `salesforce_delete_asset`, `salesforce_delete_attachment`, `salesforce_delete_bulk_ingest_job`, `salesforce_delete_bulk_query_job`, `salesforce_delete_campaign_member`, `salesforce_delete_case`, `salesforce_delete_case_comment`, `salesforce_delete_contact`, `salesforce_delete_content_document`, `salesforce_delete_content_document_link`, `salesforce_delete_contract`, `salesforce_delete_document`, `salesforce_delete_email_message`, `salesforce_delete_entitlement`, `salesforce_delete_event`, `salesforce_delete_feed_comment`, `salesforce_delete_feed_element`, `salesforce_delete_feed_item`, `salesforce_delete_individual`, `salesforce_delete_lead`, `salesforce_delete_location`, `salesforce_delete_note`, `salesforce_delete_opportunity`, `salesforce_delete_opportunity_contact_role`, `salesforce_delete_opportunity_line_item`, `salesforce_delete_order`, `salesforce_delete_order_item`, `salesforce_delete_partner`, `salesforce_delete_pricebook`, `salesforce_delete_pricebook_entry`, `salesforce_delete_product`, `salesforce_delete_return_order`, `salesforce_delete_service_contract`, `salesforce_delete_solution`, `salesforce_delete_task`, `salesforce_delete_topic`, `salesforce_delete_work_order`, `salesforce_describe_dashboard`, `salesforce_describe_global`, `salesforce_describe_quick_action`, `salesforce_describe_sobject`, `salesforce_download_attachment`, `salesforce_download_content_version`, `salesforce_download_document`, `salesforce_execute_composite_request`, `salesforce_execute_soql_query`, `salesforce_execute_sosl_search`, `salesforce_get_account`, `salesforce_get_account_history`, `salesforce_get_activity_history`, `salesforce_get_api_limits`, `salesforce_get_api_versions`, `salesforce_get_approval_layout`, `salesforce_get_approval_processes`, `salesforce_get_asset`, `salesforce_get_asset_hierarchy`, `salesforce_get_attachment`, `salesforce_get_bulk_ingest_job`, `salesforce_get_bulk_job_failed_results`, `salesforce_get_bulk_job_successful_results`, `salesforce_get_bulk_job_unprocessed_records`, `salesforce_get_bulk_query_job`, `salesforce_get_bulk_query_results`, `salesforce_get_business_hours`, `salesforce_get_campaign`, `salesforce_get_campaign_member`, `salesforce_get_campaign_statistics`, `salesforce_get_case`, `salesforce_get_case_comment`, `salesforce_get_case_history`, `salesforce_get_compact_layouts`, `salesforce_get_contact`, `salesforce_get_contact_history`, `salesforce_get_content_note`, `salesforce_get_content_version`, `salesforce_get_contract`, `salesforce_get_contract_history`, `salesforce_get_current_user`, `salesforce_get_dashboard`, `salesforce_get_dashboard_status`, `salesforce_get_default_business_hours`, `salesforce_get_document`, `salesforce_get_email_message`, `salesforce_get_email_template`, `salesforce_get_emails_for_record`, `salesforce_get_entitlement`, `salesforce_get_event`, `salesforce_get_events_for_contact`, `salesforce_get_feed_element`, `salesforce_get_feed_item`, `salesforce_get_folder`, `salesforce_get_forecast_by_category`, `salesforce_get_global_picklist_values`, `salesforce_get_group`, `salesforce_get_group_member`, `salesforce_get_holiday`, `salesforce_get_individual`, `salesforce_get_knowledge_article`, `salesforce_get_lead`, `salesforce_get_lead_history`, `salesforce_get_location`, `salesforce_get_milestone`, `salesforce_get_my_events`, `salesforce_get_my_tasks`, `salesforce_get_note`, `salesforce_get_open_activities`, `salesforce_get_opportunity`, `salesforce_get_opportunity_field_history`, `salesforce_get_opportunity_forecast_category`, `salesforce_get_opportunity_history`, `salesforce_get_opportunity_line_item`, `salesforce_get_opportunity_products_summary`, `salesforce_get_order`, `salesforce_get_order_item`, `salesforce_get_orders_for_account`, `salesforce_get_organization_info`, `salesforce_get_overdue_tasks`, `salesforce_get_page_layouts`, `salesforce_get_partner`, `salesforce_get_pipeline_by_stage`, `salesforce_get_pricebook`, `salesforce_get_pricebook_entry`, `salesforce_get_product`, `salesforce_get_product_pricing`, `salesforce_get_profile`, `salesforce_get_queue_sobjects`, `salesforce_get_recent_activities`, `salesforce_get_recently_viewed`, `salesforce_get_record_type`, `salesforce_get_record_type_by_name`, `salesforce_get_report`, `salesforce_get_return_order`, `salesforce_get_role_hierarchy`, `salesforce_get_service_appointment`, `salesforce_get_service_contract`, `salesforce_get_service_resource`, `salesforce_get_service_territory`, `salesforce_get_solution`, `salesforce_get_standard_pricebook`, `salesforce_get_tabs`, `salesforce_get_task`, `salesforce_get_tasks_due_today`, `salesforce_get_tasks_for_contact`, `salesforce_get_themes`, `salesforce_get_topic`, `salesforce_get_topics_for_record`, `salesforce_get_upcoming_events`, `salesforce_get_user`, `salesforce_get_user_permissions`, `salesforce_get_user_role`, `salesforce_get_users_in_group`, `salesforce_get_work_order`, `salesforce_like_feed_element`, `salesforce_link_solution_to_case`, `salesforce_list_account_contact_roles`, `salesforce_list_accounts`, `salesforce_list_active_opportunity_stages`, `salesforce_list_all_groups`, `salesforce_list_apex_actions`, `salesforce_list_assets`, `salesforce_list_assigned_resources`, `salesforce_list_attachments`, `salesforce_list_authorization_form_consents`, `salesforce_list_bulk_ingest_jobs`, `salesforce_list_bulk_query_jobs`, `salesforce_list_business_hours`, `salesforce_list_campaign_member_statuses`, `salesforce_list_campaign_members`, `salesforce_list_campaigns`, `salesforce_list_case_comments`, `salesforce_list_case_milestones`, `salesforce_list_case_solutions`, `salesforce_list_case_statuses`, `salesforce_list_cases`, `salesforce_list_chatter_groups`, `salesforce_list_contact_point_consents`, `salesforce_list_contacts`, `salesforce_list_content_documents`, `salesforce_list_content_versions`, `salesforce_list_contract_statuses`, `salesforce_list_contracts`, `salesforce_list_custom_invocable_actions`, `salesforce_list_dashboards`, `salesforce_list_data_category_groups`, `salesforce_list_documents`, `salesforce_list_email_message_relations`, `salesforce_list_email_messages`, `salesforce_list_email_templates`, `salesforce_list_entitlement_processes`, `salesforce_list_entitlements`, `salesforce_list_events`, `salesforce_list_feed_comments`, `salesforce_list_feed_items`, `salesforce_list_flow_actions`, `salesforce_list_folders`, `salesforce_list_group_members`, `salesforce_list_holidays`, `salesforce_list_individuals`, `salesforce_list_knowledge_articles`, `salesforce_list_lead_statuses`, `salesforce_list_leads`, `salesforce_list_locations`, `salesforce_list_milestones`, `salesforce_list_notes`, `salesforce_list_opportunities`, `salesforce_list_opportunity_contact_roles`, `salesforce_list_opportunity_line_items`, `salesforce_list_opportunity_stages`, `salesforce_list_order_items`, `salesforce_list_order_statuses`, `salesforce_list_orders`, `salesforce_list_org_wide_email_addresses`, `salesforce_list_partners`, `salesforce_list_periods`, `salesforce_list_permission_sets`, `salesforce_list_pricebook_entries`, `salesforce_list_pricebooks`, `salesforce_list_process_instance_steps`, `salesforce_list_process_instance_work_items`, `salesforce_list_process_instances`, `salesforce_list_products`, `salesforce_list_profiles`, `salesforce_list_public_case_comments`, `salesforce_list_public_groups`, `salesforce_list_queues`, `salesforce_list_quick_actions_global`, `salesforce_list_record_types`, `salesforce_list_report_instances`, `salesforce_list_reports`, `salesforce_list_return_order_line_items`, `salesforce_list_return_orders`, `salesforce_list_service_appointments`, `salesforce_list_service_contracts`, `salesforce_list_service_resources`, `salesforce_list_service_territories`, `salesforce_list_setup_audit_trail`, `salesforce_list_sobjects`, `salesforce_list_solution_statuses`, `salesforce_list_solutions`, `salesforce_list_task_statuses`, `salesforce_list_tasks`, `salesforce_list_topic_assignments`, `salesforce_list_topics`, `salesforce_list_user_licenses`, `salesforce_list_user_roles`, `salesforce_list_users`, `salesforce_list_users_by_profile`, `salesforce_list_users_by_role`, `salesforce_list_work_order_line_items`, `salesforce_list_work_order_statuses`, `salesforce_list_work_orders`, `salesforce_parameterized_search`, `salesforce_post_comment`, `salesforce_post_feed_element`, `salesforce_recall_approval`, `salesforce_refresh_dashboard`, `salesforce_remove_group_member`, `salesforce_remove_permission_set`, `salesforce_remove_topic_from_record`, `salesforce_run_report_async`, `salesforce_run_report_sync`, `salesforce_schedule_meeting`, `salesforce_search_accounts`, `salesforce_search_assets`, `salesforce_search_campaign_members`, `salesforce_search_campaigns`, `salesforce_search_cases`, `salesforce_search_contacts`, `salesforce_search_contracts`, `salesforce_search_knowledge_articles`, `salesforce_search_leads`, `salesforce_search_locations`, `salesforce_search_opportunities`, `salesforce_search_orders`, `salesforce_search_pricebook_entries`, `salesforce_search_solutions`, `salesforce_search_suggest_records`, `salesforce_search_topics`, `salesforce_search_users`, `salesforce_search_work_orders`, `salesforce_send_email`, `salesforce_sobject_collections_create`, `salesforce_sobject_collections_delete`, `salesforce_sobject_collections_update`, `salesforce_transfer_record_ownership`, `salesforce_unified_get_group`, `salesforce_unified_get_me`, `salesforce_unified_get_organization`, `salesforce_unified_get_role`, `salesforce_unified_get_user`, `salesforce_unified_list_groups`, `salesforce_unified_list_organizations`, `salesforce_unified_list_roles`, `salesforce_unified_list_users`, `salesforce_unlink_solution_from_case`, `salesforce_update_account`, `salesforce_update_account_contact_role`, `salesforce_update_asset`, `salesforce_update_campaign_member`, `salesforce_update_case`, `salesforce_update_case_comment`, `salesforce_update_contact`, `salesforce_update_contract`, `salesforce_update_entitlement`, `salesforce_update_event`, `salesforce_update_individual`, `salesforce_update_lead`, `salesforce_update_location`, `salesforce_update_note`, `salesforce_update_opportunity`, `salesforce_update_opportunity_contact_role`, `salesforce_update_opportunity_forecast_category`, `salesforce_update_opportunity_line_item`, `salesforce_update_order`, `salesforce_update_order_item`, `salesforce_update_pricebook`, `salesforce_update_pricebook_entry`, `salesforce_update_product`, `salesforce_update_return_order`, `salesforce_update_service_appointment`, `salesforce_update_service_contract`, `salesforce_update_service_resource`, `salesforce_update_solution`, `salesforce_update_task`, `salesforce_update_topic`, `salesforce_update_user`, `salesforce_update_work_order`, `salesforce_upload_bulk_job_data` `data-sync` Added scheduled data sync to seventeen reference list actions — organization details, opportunity stages, case, lead, order, solution, task, work order, and contract statuses, business hours, holidays, fiscal periods, milestone types, entitlement processes, user licenses, and org-wide email addresses — so these collections can be kept in sync and read back without calling Salesforce on every request. `salesforce_list_active_opportunity_stages`, `salesforce_list_business_hours`, `salesforce_list_case_statuses`, `salesforce_list_contract_statuses`, `salesforce_list_entitlement_processes`, `salesforce_list_holidays`, `salesforce_list_lead_statuses`, `salesforce_list_milestones`, `salesforce_list_opportunity_stages`, `salesforce_list_order_statuses`, `salesforce_list_org_wide_email_addresses`, `salesforce_list_periods`, `salesforce_list_solution_statuses`, `salesforce_list_task_statuses`, `salesforce_list_user_licenses`, `salesforce_list_work_order_statuses`, `salesforce_unified_list_organizations` `bug-fix` Fixed the IAM unified_get_me response — the embedded user status now returns the same value and source value pair the user actions already return, instead of a plain string. # Salesforce Marketing Cloud Source: https://docs.stackone.com/connectors/salesforcemc/index How to set up the Salesforce Marketing Cloud connector, plus the actions that are available.

Previewv1.3.0

See changelog

57 actions · 1 auth method

Marketing IAM

Previewv3.0.0

See changelog

52 actions · 1 auth method

Customer Support Ticketing

v2.0.1

See changelog

69 actions · 1 auth method

CRM IAM

v1.2.0

See changelog

33 actions · 3 events · 2 auth methods

CMS IAM

Betav1.1.0

See changelog

15 actions · 1 auth method

Vendor Management System Analytics

Betav1.1.0

See changelog

117 actions · 1 auth method

ERP

v3.0.0

See changelog

120 actions · 1 auth method

HRIS ATS LMS

Betav0.2.0

See changelog

76 actions · 2 auth methods

HRIS

v1.0.0

7 actions · 1 auth method

Betav1.0.0

61 actions · 1 auth method

Analytics IAM

Betav1.1.0

See changelog

20 actions · 1 auth method

v1.3.1

See changelog

110 actions · 1 auth method

Messaging IAM

v1.0.0

69 actions · 1 auth method

Security

v3.0.0

See changelog

85 actions · 15 events · 3 auth methods

Observability IAM

v1.2.0

See changelog

77 actions · 19 events · 2 auth methods

ITSM Ticketing IAM

Previewv1.1.0

See changelog

60 actions · 1 auth method

HRIS

v1.2.0

See changelog

33 actions · 1 auth method

Documents

v1.2.0

See changelog

45 actions · 6 events · 1 auth method

Logistics

Previewv1.4.0

90 actions · 22 events · 1 auth method

E-Commerce IAM

v1.3.0

See changelog

92 actions · 6 events · 1 auth method

Project Management

Previewv1.2.0

See changelog

55 actions · 1 auth method

HRIS

v5.0.0

See changelog

51 actions · 4 auth methods

Messaging IAM

Betav1.1.0

See changelog

60 actions · 1 auth method

Legal

v1.1.1

See changelog

70 actions · 23 events · 1 auth method

Localization

v2.1.0

See changelog

169 actions · 15 events · 1 auth method

ATS IAM

Previewv1.3.0

See changelog

203 actions · 9 events · 2 auth methods

Project Management IAM

v1.4.0

See changelog

98 actions · 3 auth methods

Databases IAM

v1.2.0

See changelog

71 actions · 2 events · 2 auth methods

Developer Tools

Betav1.1.0

See changelog

32 actions · 1 auth method

ATS

Previewv1.3.0

See changelog

102 actions · 6 events · 1 auth method

Developer Tools IAM

Previewv1.2.0

See changelog

54 actions · 1 auth method

Security IAM

Betav0.2.0

See changelog

6 actions · 1 auth method

ATS

Betav1.0.0

47 actions · 1 auth method

ATS

Betav0.3.0

See changelog

82 actions · 1 auth method

CRM

Betav1.2.0

See changelog

33 actions · 1 auth method

Expense Management IAM

Previewv2.1.0

See changelog

99 actions · 39 events · 1 auth method

Contract Lifecycle Management

Previewv1.1.0

See changelog

47 actions · 1 auth method

Media

Betav1.1.0

See changelog

24 actions · 3 auth methods

Previewv1.3.0

See changelog

137 actions · 96 events · 1 auth method

Payments E-Commerce IAM

v2.0.2

See changelog

27 actions · 10 events · 2 auth methods

E-Commerce

v1.0.0

637 actions · 1 auth method

MCP

v1.0.0

4 actions · 1 auth method

MCP

Betav1.1.1

See changelog

46 actions · 1 auth method

HRIS

Previewv0.1.0

See changelog

7 actions · 1 auth method

IAM Observability

Previewv1.1.0

See changelog

138 actions · 49 events · 1 auth method

Payments Billing IAM

Betav0.2.0

See changelog

81 actions · 2 auth methods

Events

Betav1.1.0

See changelog

47 actions · 1 auth method

CRM IAM

v2.1.1

See changelog

138 actions · 9 events · 2 auth methods

Databases IAM

v2.1.1

See changelog

115 actions · 1 auth method

Surveys IAM

v1.2.0

See changelog

62 actions · 2 events · 1 auth method

Developer Tools

Previewv1.2.0

See changelog

122 actions · 23 events · 1 auth method

Analytics IAM

Betav1.1.0

See changelog

34 actions · 1 auth method

ATS

Previewv1.2.2

See changelog

71 actions · 2 auth methods

Data Integration IAM

Betav1.2.0

See changelog

43 actions · 1 auth method

LMS IAM

v1.2.0

See changelog

44 actions · 28 events · 1 auth method

ATS

Betav2.1.0

See changelog

36 actions · 7 events · 1 auth method

Customer Support Ticketing

Betav0.2.0

See changelog

83 actions · 1 auth method

Background Checks IAM

Previewv2.1.2

See changelog

62 actions · 8 events · 1 auth method

CRM IAM

v1.2.0

See changelog

106 actions · 16 events · 1 auth method

ATS

Betav1.2.0

See changelog

102 actions · 1 auth method

Device Management IAM Meetings

Previewv2.2.0

See changelog

125 actions · 124 events · 1 auth method

Project Management IAM

v1.2.0

See changelog

38 actions · 28 events · 1 auth method

Messaging

v3.1.0

See changelog

130 actions · 10 events · 1 auth method

Infrastructure IAM

v1.2.0

See changelog

4 actions · 1 auth method

Previewv1.1.0

See changelog

44 actions · 1 auth method

LMS

v1.0.0

See changelog

13 actions · 1 auth method

Previewv1.0.0

50 actions · 2 auth methods

Advertising

v3.1.0

See changelog

67 actions · 4 auth methods

IAM Time Tracking Accounting

Betav0.2.0

See changelog

6 actions · 1 auth method

Notetaker

v2.0.0

See changelog

62 actions · 25 events · 2 auth methods

Project Management IAM

v2.1.0

See changelog

92 actions · 29 events · 1 auth method

IAM Time Tracking

Betav1.1.0

See changelog

70 actions · 1 auth method

ATS IAM

Previewv1.1.0

See changelog

133 actions · 67 events · 1 auth method

Project Management

Betav1.1.0

See changelog

56 actions · 2 auth methods

ATS IAM

Previewv0.3.1

See changelog

75 actions · 1 auth method

Accounting

v2.2.1

See changelog

59 actions · 20 events · 4 auth methods

Messaging Telephony IAM

v1.3.1

See changelog

36 actions · 1 event · 1 auth method

Surveys IAM

Previewv1.1.0

See changelog

9 actions · 1 auth method

LMS

v3.0.0

See changelog

56 actions · 2 auth methods

HRIS IAM

Previewv2.0.1

See changelog

163 actions · 1 event · 1 auth method

HRIS ATS

v1.2.0

See changelog

23 actions · 1 event · 2 auth methods

Marketing IAM

Previewv1.1.0

See changelog

64 actions · 24 events · 1 auth method

ERP

Betav0.2.0

See changelog

70 actions · 1 auth method

Customer Support

v1.2.0

See changelog

22 actions · 2 events · 1 auth method

Background Checks IAM

v2.1.0

See changelog

100 actions · 2 auth methods

Media

Previewv1.2.1

See changelog

232 actions · 2 auth methods

ATS IAM

v1.3.0

See changelog

57 actions · 1 event · 1 auth method

CRM IAM

v1.0.0

See changelog

21 actions · 1 auth method

Weather

Previewv3.1.1

See changelog

115 actions · 27 events · 2 auth methods

IAM Messaging Meetings

v2.2.0

See changelog

98 actions · 15 events · 2 auth methods

CMS E-Commerce IAM

v2.0.0

See changelog

35 actions · 4 events · 1 auth method

Betav1.1.1

See changelog

35 actions · 1 auth method

ATS

v2.0.0

See changelog

81 actions · 14 events · 2 auth methods

Messaging IAM

v1.0.0

See changelog

20 actions · 1 auth method

Security

v1.0.2

See changelog

15 actions · 3 auth methods

Knowledge Management

v1.0.0

See changelog

12 actions · 1 auth method

Marketing

Previewv2.0.0

See changelog

63 actions · 19 events · 2 auth methods

Media

v2.1.0

See changelog

72 actions · 1 auth method

E-Commerce

v2.2.3

See changelog

70 actions · 7 events · 1 auth method

ATS

v1.4.1

See changelog

162 actions · 3 auth methods

HRIS ATS LMS

Betav1.1.0

See changelog

59 actions · 1 auth method

IAM

Betav0.2.0

See changelog

78 actions · 1 auth method

HRIS

Betav0.2.0

See changelog

266 actions · 1 auth method

IAM Documents

Betav0.1.0

See changelog

234 actions · 1 auth method

IAM AI Security

v2.1.1

See changelog

11 actions · 3 events · 2 auth methods

Customer Support Ticketing

v1.2.0

See changelog

48 actions · 43 events · 1 auth method

IAM Project Management

Previewv2.0.0

See changelog

60 actions · 2 auth methods

Marketing Messaging

v1.3.0

See changelog

77 actions · 12 events · 1 auth method

Accounting IAM

v1.1.0

See changelog

79 actions · 1 auth method

LMS

v2.1.0

See changelog

55 actions · 3 events · 1 auth method

Media

v1.1.0

See changelog

34 actions · 1 auth method

HRIS IAM

v2.3.0

See changelog

72 actions · 109 events · 3 auth methods

Customer Support Ticketing

v1.1.0

See changelog

9 actions · 1 auth method

Background Checks

v1.4.0

See changelog

115 actions · 46 events · 1 auth method

Accounting IAM

v1.2.0

See changelog

51 actions · 23 events · 1 auth method

Project Management

Previewv1.3.0

See changelog

136 actions · 52 events · 1 auth method

CRM IAM

v3.1.0

See changelog

45 actions · 1 auth method

Customer Support Ticketing

v1.1.0

See changelog

73 actions · 1 auth method

HRIS

v1.1.0

See changelog

63 actions · 1 auth method

ATS IAM

v1.0.0

See changelog

9 actions · 1 auth method

Documents Internal

v1.3.0

See changelog

87 actions · 44 events · 1 auth method

Project Management IAM

v1.4.1

See changelog

66 actions · 39 events · 2 auth methods

Messaging IAM Meetings

Betav1.2.0

See changelog

76 actions · 2 auth methods

CRM Marketing IAM

Betav1.1.0

See changelog

56 actions · 9 events · 1 auth method

Billing

StackOne connector build process: you request a connector, StackOne builds it through automated QA, AI optimization, and manual QA, then delivers it for you to use or fork

StackOne builds and maintains the connector for you. Delivery defined for plans with SLAs. - **Fast turnaround:** typically days, not weeks (when API access is provided). - **Full support:** StackOne handles API mapping and authentication. - **QA pipeline:** AI-driven optimization and manual verification. - **Fork & customize:** optionally fork and edit actions after delivery. **[Request it from StackOne](https://www.stackone.com/demo)** ### Build it yourself AI-assisted connector development workflow: your prompt goes to your coding assistant, which uses StackOne's MCP and skills to research, build, and test a connector.yaml that you deploy through your own CI/CD

AI-assisted connector development workflow: your prompt goes to your coding assistant, which uses StackOne's MCP and skills to research, build, and test a connector.yaml that you deploy through your own CI/CD

Connectors are defined as code, so you build and publish them on your own schedule. - **AI-assisted:** use StackOne's MCP and skills to turn provider docs into YAML. - **Test locally:** run actions against a sandbox account. - **Full control:** version, test, and publish when you choose. - **Your environments:** publish through your existing CI/CD. **[Build it yourself](/connector-building/first-connector)** # First Connector Source: https://docs.stackone.com/connector-building/first-connector Build, test, and deploy your first StackOne connector. Custom connector building is only available on certain plans. Each custom connector takes up one of your plan's slots. See [plans and pricing](https://www.stackone.com/pricing/). A connector turns a third-party API into agent-ready actions, defined as YAML. This guide builds one from scratch with the [StackOne CLI](/connector-building/stackone-cli) and its agent, then pushes it to your project. To adapt a connector that already exists instead, see [Customizing Connectors](/connector-building/customizing-connectors). ## Before you start The CLI needs **Node.js 22.22 or later**. Nothing else is required. - Open **Terminal** (press `Cmd + Space`, type Terminal, press Enter). - Check what you have: `node --version`. - No Node.js 22.22+? Install it from [nodejs.org](https://nodejs.org/). - Open **Command Prompt** or **PowerShell** from the Start menu. - Check what you have: `node --version`. - No Node.js 22.22+? Install it from [nodejs.org](https://nodejs.org/). - Open your terminal application. - Check what you have: `node --version`. - Install Node.js 22.22+ from [nodejs.org](https://nodejs.org/) or [NodeSource](https://github.com/nodesource/distributions), since distribution packages are often older. Create an [API key](/embed/api-keys) with the `connectors:read`, `connectors:write`, and `credentials:read` scopes. Install the StackOne CLI globally via npm: ```bash npm install -g @stackone/cli ``` The `-g` flag installs the CLI globally so the `stackone` command is available in any directory. Verify the install. It prints the installed version: ```bash stackone --version ``` Make a directory to hold your connectors and move into it: ```bash mkdir custom-connectors && cd custom-connectors ``` From inside your working directory, set up the agent: ```bash stackone agent setup --local ``` This authenticates you, writes an `.mcp.json` so your AI assistant gets StackOne's tools, and installs the connector-building skills, slash commands, and subagents into `.claude/` along with a guide block in `CLAUDE.md`. The CLI owns everything under `.claude/`, so re-run `stackone agent sync` after each CLI update to pick up new skills and commands. Create a named profile so deployment commands like `stackone push` can authenticate without you pasting your API key each time: ```bash stackone init ``` You'll be prompted for a profile label and an API key. Paste the key you generated above. Profiles point at production unless you pass `--env staging`, so create one of each if you deploy to both, then reference them with `--profile [profile-label]`. Open [Claude Code](https://claude.com/claude-code) in your working directory: ```bash claude ``` It picks up the `.mcp.json` and the skills that `agent setup --local` just installed. Approve the StackOne MCP server when prompted, so the agent can reach StackOne's tools. Then run the onboarding command that `agent setup --local` installed, which walks you through the build rather than leaving you to describe it: ```text /connector-onboarding ``` It asks which provider you're connecting to and what kind of connector you want, then works through authentication, the endpoints worth exposing, and the actions themselves, confirming each part with you before moving on. This command needs CLI 1.47.0 or later. Earlier versions install the other connector skills but skip this one, so if it isn't listed, update the CLI and re-run `stackone agent sync`. Have the provider's API documentation to hand, along with the authentication type you plan to use. You can also skip it and describe what you want in plain language, letting the agent work out the endpoints, pagination, and field mappings from the provider's documentation: ```text I want to connect to Acme HR, our HR system. Their API docs are at https://developer.acme.com/reference and we authenticate with an API key. I want to be able to look up who works at the company, along with their job title and manager. ``` The agent reports the directory it wrote the connector to. Substitute that path for `[connector-dir]` below. `validate` checks the YAML against the connector schema and reports what's malformed or missing. `--watch` keeps it running so it rechecks every time you save: ```bash stackone validate [connector-dir] --watch ``` `run` executes a single action for real against the provider, so you see what it returns rather than what the YAML claims. Before you push, point it at local account and credential files: ```bash echo '{"environment": "production", "provider": "[provider]"}' > account.json echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json ``` Add `credentials.json` to `.gitignore` so credentials never reach version control. `--debug` adds the raw request and response and each step's inputs and outputs: ```bash stackone run --connector [connector-dir]/[provider].connector.s1.yaml \ --account account.json --credentials credentials.json \ --action-id [action-id] --debug ``` Once the connector is pushed and an account is linked, swap both files for `--account-id [account-id] --profile [profile-label]`. That path needs a profile, because the CLI fetches the stored credentials from the API. Expect to go back and forth between building and testing. Tell the agent what you saw and rerun the action until it returns what you want. What `--debug` surfaces, and the common symptoms with their causes. `push` uploads the connector to your project's registry, which is what makes it available to link accounts against. `--profile` is the name you set with `stackone init`: ```bash stackone push [connector-dir] --profile [profile-label] ``` Connectors are code, so keeping them in version control gives you history and review as they change. It's also what publishing through [GitHub CI/CD](/connector-building/github-ci-cd) builds on. Covers authentication patterns, testing against an account, and the iterate loop. Every field, step function, and expression the schema supports. Pull an existing connector, change it, and push it back. Release new versions without breaking existing linked accounts. # Customizing Connectors Source: https://docs.stackone.com/connector-building/customizing-connectors Use the StackOne CLI to pull, edit, test, and push changes to an existing connector. Custom connector building is only available on certain plans. Each custom connector takes up one of your plan's slots. See [plans and pricing](https://www.stackone.com/pricing/). Adapt an existing connector — its actions, fields, and data mappings — by pulling it down with the [StackOne CLI](/connector-building/stackone-cli), editing the YAML, and pushing your changes back. ```bash npm install -g @stackone/cli ``` Set up a profile with your API key. Customizing needs an [API key](/embed/api-keys#scopes) with the `connectors:read` and `connectors:write` scopes. ```bash stackone init ``` Download the connector's files to your machine. ```bash stackone pull --connector [provider] --profile [profile-label] ``` Files save to `./connectors/[provider]/` by default. Append a version to pull a specific one, such as `--connector [provider]@1.0.0`, or pass `--output-path` to save elsewhere. Edit `[provider].connector.s1.yaml` to adjust authentication, add or change actions, and map provider fields to your own schema. Every field, step function, and expression the schema supports. Check syntax and structure. `--watch` re-runs on every save. ```bash stackone validate ./connectors/[provider]/ --watch ``` Run an action against a linked account to confirm your changes behave as expected. ```bash stackone run \ --connector [provider].connector.s1.yaml \ --account-id [account-id] \ --action-id [action-id] ``` Upload the updated connector back to StackOne. ```bash stackone push ./connectors/[provider]/ --profile [profile] ``` All commands, flags, and test-file formats. # Build Workflow Source: https://docs.stackone.com/connector-building/build-workflow Pull first, get authentication working, then build actions and iterate. Building a connector is a loop, and the order matters: every action you write depends on authentication already working. Validate each stage before moving to the next. ```mermaid flowchart LR A[Pull existing or create] --> B[Build authentication] B --> C[Connect an account] C --> D[Build actions] D --> E[Test and debug] E --> D E --> F[Publish] style A fill:#ecfdf5,stroke:#10b981,color:#065f46 style B fill:#ecfdf5,stroke:#10b981,color:#065f46 style C fill:#ecfdf5,stroke:#10b981,color:#065f46 style D fill:#dbeafe,stroke:#3b82f6,color:#1e40af style E fill:#dbeafe,stroke:#3b82f6,color:#1e40af style F fill:#fef9c3,stroke:#eab308,color:#854d0e ``` This assumes you've already got the [CLI installed and authenticated](/connector-building/first-connector). ## Pull existing or create Always check whether a connector already exists before writing one, since starting from the registry gives you a working foundation. Files save to `./connectors/[provider]/` by default: ```bash stackone pull --connector [provider] --profile [profile-label] ls connectors/[provider]/ ``` If nothing exists to pull, the agent writes the files for you, laid out as described in [File Structure](/connector-yaml-reference/file-structure). ## Build authentication Don't move on until authentication works. Everything else depends on it. Configure authentication in the main connector file. The common patterns: ```yaml authentication: - custom: type: custom label: API Key authorization: type: bearer token: $.credentials.apiKey configFields: - key: apiKey label: API Key type: password required: true secret: true testActionsIds: - list_users # simple action to test authentication ``` ```yaml authentication: - custom: type: custom label: API Key authorization: type: none customHeaders: X-API-Key: $.credentials.apiKey configFields: - key: apiKey label: API Key type: password required: true secret: true ``` ```yaml authentication: - custom: type: custom label: Basic Auth authorization: type: basic username: $.credentials.username password: $.credentials.password configFields: - key: username label: Username type: text required: true - key: password label: Password type: password required: true secret: true ``` Add one simple action — a `list_users` or equivalent — and use it to prove authentication works before building anything else. ## Connect an account Most providers offer sandbox or developer accounts. Check the provider's developer portal to sign up and generate credentials, and note any rate limits or restrictions that apply to sandbox access. For local development, keep the account config and credentials in separate files: ```bash echo '{"environment": "production", "provider": "[provider]"}' > account.json echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json ``` Add `credentials.json` to `.gitignore`. Keep sandbox credentials separate from production ones. Then run your test action against those files: ```bash stackone run \ --connector connectors/[provider]/[provider].connector.s1.yaml \ --account account.json \ --credentials credentials.json \ --action-id list_users \ --debug ``` Rather than local credential files, you can push the connector and link an account in the dashboard, then run against that account by ID: ```bash stackone push connectors/[provider]/ --profile [profile] # link the account in the dashboard, then: stackone run \ --connector connectors/[provider]/[provider].connector.s1.yaml \ --account-id [account-id] \ --action-id list_users ``` `[profile]` is the name you set with `stackone init`. A pushed connector appears in the dashboard alongside the StackOne ones, so linking an account against it is the same flow as any other connector: [create a connector profile](/gateway/quickstart#setup-connector-profile), then [link an account](/gateway/quickstart#link-account). Other linking methods are covered in [Linking Accounts](/connect/managing-connectors/linking-accounts). ## Build actions and iterate With authentication proven, add your remaining actions to the resource partials. Each action is built from [step functions](/connector-yaml-reference/step-functions/overview). Then cycle: validate the syntax, run the action with `--debug`, fix, repeat. If the actions should return a normalized shape rather than the provider's own, see [Defined Output Schemas](/connector-building/defined-output-schemas). ```bash stackone validate connectors/[provider]/ --watch ``` Running `validate` with `--watch` keeps checking as you edit, so you catch schema mistakes without rerunning by hand. The [Playground](/embed/call-actions/troubleshooting/playground) also runs your connector's actions in natural language, which is handy for a quick check without the CLI. ## Debugging Add `--debug` to any `stackone run` to surface: - The raw HTTP request sent to the provider: URL, method, headers, body - The full response body, before any mapping is applied - The inputs and outputs of each step - The resolved values of any JSONPath or JEXL expressions When mapping produces something unexpected, work backwards from the raw response: Temporarily return the unmapped data so you can see what the provider actually sent: ```yaml result: data: $.steps.get_employees.output.data # raw, before map_fields ``` Run with `--debug` and inspect the real paths: ```bash stackone run --debug ... | jq '.steps.get_employees.output' ``` Start with a single field in `map_fields`, confirm it resolves, then add the rest. Inline fields in `map_fields` reference the field directly (`$.email`), not via the step (`$.get_employees.email`). | Symptom | Likely cause | Fix | |---------|--------------|-----| | 401 Unauthorized | Invalid credentials | Check the API key, regenerate if needed | | Empty data array | Wrong `dataKey` path | Use `--debug` to verify the actual response structure | | Null field values | Incorrect expression path | Check the nested paths match the real response | | Pagination returns the same data | Wrong `iterator.key` | Check the provider's docs for the expected cursor parameter name | | Enum not translated | `matchExpression` case mismatch | The provider might return `"ACTIVE"` rather than `"Active"` | ## Publish When the connector behaves, push it to your project's registry so linked accounts can use it: ```bash stackone push connectors/[provider]/ --profile [profile] ``` For team workflows, connectors are usually published through a Git pipeline rather than a direct push. See [GitHub CI/CD](/connector-building/github-ci-cd). Release new versions without breaking existing linked accounts. ### Other ways to test Once it's published, `stackone run` is no longer the only way in. Each of these exercises the deployed version against a linked account's real credentials, so they need a [connector profile](/gateway/quickstart#setup-connector-profile) and a [linked account](/gateway/quickstart#link-account) first: | Surface | Use it to | |---|---| | [Request Tester](/embed/call-actions/troubleshooting/request-tester) | Pick an action in the dashboard, fill in parameters, and inspect the response | | [`POST /actions/rpc`](/embed/call-actions/rpc-http) | Call the action the way your own backend will | | [Playground](/embed/call-actions/troubleshooting/playground) | Check an agent picks the right action from your descriptions | An action only shows up on these surfaces once it's enabled on the [connector profile](/secure/scoping-connectors). ## Next steps Map provider responses onto a schema of your own. The building blocks each action is made of. Full command reference for pull, validate, run, and push. Define the events your connector emits. # Defined Output Schemas Source: https://docs.stackone.com/connector-building/defined-output-schemas Map provider responses onto an output schema you define, so every provider in a category returns the same shape. A connector can pass the provider's response through as-is, or map it onto an output schema you define so every provider in a category returns the same shape. That mapping is where most of the work goes, and where most of the mistakes are. ## Mapping to your schema Two step functions do the work, both documented in full on [Step Functions](/connector-yaml-reference/step-functions/overview): | Step function | Role | |---|---| | [`map_fields`](/connector-yaml-reference/step-functions/map-fields) | Maps provider fields onto your `targetFieldKey` names, including enum translation via `enumMapper` | | [`typecast`](/connector-yaml-reference/step-functions/typecast) | Runs after `map_fields` to coerce the mapped values to their declared types | Use `version: "2"` for both `map_fields` and `typecast`. ## Give the agent your target schema Your target schema is the thing you'd otherwise restate for every provider you map, so write it down where the agent can read it: ````markdown --- name: Employee Sync Schema description: Target schema for employee data synchronization --- # Employee Sync Schema ## Target schema | Field | Type | Required | Notes | |-------|------|----------|-------| | id | string | yes | Unique identifier | | email | string | yes | Primary email | | first_name | string | yes | | | last_name | string | yes | | | status | enum | yes | Values: active, inactive, terminated | | department | string | no | | | hire_date | datetime_string | no | ISO 8601 format | ## Enum mappings ### status | Provider value | Schema value | |----------------|--------------| | Active, active, ACTIVE | active | | Inactive, inactive, INACTIVE | inactive | | Terminated, terminated, TERMINATED | terminated | | * (default) | unknown | ```` With that in place, the agent maps a new provider's employee response to your schema without being asked, including the enum normalization that is easy to get subtly wrong by hand. ## Checklist Before publishing a connector with a defined output schema, verify: - [ ] Target schema documented before building - [ ] All required fields identified - [ ] Field types specified (string, number, enum, datetime_string) - [ ] Enum values defined with mappings - [ ] `fieldConfigs` map all schema fields - [ ] `targetFieldKey` uses your schema names, not the provider's - [ ] Nested paths verified against the actual response - [ ] Enum mappings handle every provider value plus a default case - [ ] `cursor.enabled: true` for list actions - [ ] `dataKey` path verified with `--debug` - [ ] `nextKey` path verified with `--debug` - [ ] `result.next` returns the cursor for the next page - [ ] Tested against the first page, next page, last page, and empty results - [ ] `map_fields` step with `version: "2"` - [ ] `typecast` step with `version: "2"` - [ ] Correct `dataSource` references between steps ## Related The build and debug loop this fits into. Full reference for `map_fields`, `typecast`, and the rest. JSONPath and JEXL for the expressions in your mappings. # GraphQL Actions Source: https://docs.stackone.com/connector-building/graphql-actions Call a provider's GraphQL API from a connector using the request step function. For GraphQL APIs, use the `request` step function with `method: post` and the query in the body. Pass the query and its variables as separate `body` args. ```yaml steps: - stepId: graphql_query stepFunction: functionName: request parameters: url: /graphql method: post args: - name: query value: | query ListUsers($first: Int, $after: String) { users(first: $first, after: $after) { nodes { id name email } pageInfo { hasNextPage endCursor } } } in: body - name: variables value: first: '{{$.inputs.page_size ?? 50}}' after: '{{$.inputs.cursor ?? null}}' in: body ``` ## Error handling GraphQL returns `200` even for errors, so check the response's `errors` field rather than the status code: ```yaml - stepId: check_errors condition: '{{present(steps.graphql_query.output.data.errors)}}' stepFunction: # Handle the error case. ``` ## Best practices - Define variables for every dynamic value, and pass them in a separate `variables` object rather than inlining them in the query string. - Request only the fields you need, and use fragments for reusable field selections. - For pagination, use the provider's cursor fields, such as `pageInfo.hasNextPage` and `pageInfo.endCursor`. Keep the query static and supply values through `variables`: ```yaml args: - name: query value: 'query GetUser($id: ID!) { user(id: $id) { name } }' in: body - name: variables value: id: $.inputs.user_id in: body ``` ## Related The request step used to issue the GraphQL POST. JEXL defaults and conditions used in the query variables and error check. # Implementing Events Source: https://docs.stackone.com/connector-building/implementing-events Define the events your connector emits in its YAML, so StackOne can normalize and deliver them. Events let your connector turn a provider's webhooks into normalized StackOne events. As a connector author, you declare the events in the connector YAML; StackOne handles subscription, signature verification, and delivery to a [webhook](/connect/webhooks). This is the **producing** side. For how a consumer subscribes and receives events, see [Webhook Events](/connect/webhooks); for the concept, see [Events](/gateway/concepts/events). ## Where events live Event handlers go in a `{provider}.events.s1.partial.yaml` partial, referenced from the connector's `events` block rather than the top-level `actions`. See [File structure](/connector-yaml-reference/file-structure) for the layout. ## The events block The `events` block has four parts, from provisioning a receiver to handling a delivery: 1. `setup` runs the webhook receiver lifecycle with the provider (create, activate, and delete the receiver). 2. `externalAccountIdExtractor` resolves which linked account an incoming event belongs to. 3. `router` maps each incoming payload to an event action. 4. `actions[]` hold the `actionType: event` handlers that process the matched event. ## Anatomy of an event Each event is an action with `actionType: event`. It names the provider's native events, maps the incoming webhook payload to its `inputs`, and emits a normalized event with the `emit_event` step function: ```yaml # {provider}.events.s1.partial.yaml - actionId: webhook_employee_created categories: - hris actionType: event label: Employee Created description: Processes employee.created events fired when a new employee is added. providerEvents: - employee.created # the provider's native event name(s) inputs: # shape of the incoming webhook payload - name: type type: string in: body - name: triggeredAt type: string in: body - name: data type: object in: body properties: - name: employeeId type: string steps: - stepId: emit description: Emit the normalized event to the StackOne dispatcher. stepFunction: functionName: emit_event parameters: event: eventId: $.inputs.data.employeeId eventType: $.inputs.type eventDate: $.inputs.triggeredAt data: $.inputs.data result: statusCode: 200 # acknowledge receipt to the provider body: status: OK ``` | Field | Purpose | |-------|---------| | `actionType: event` | Marks the action as an inbound event handler, not an API call. | | `providerEvents` | The provider's native event names this handler accepts. | | `inputs` | The fields of the incoming webhook payload. | | `emit_event` step | Maps the payload to a normalized event (`eventId`, `eventType`, `eventDate`, `data`). | | `result` | The `200` acknowledgement returned to the provider. | ## Registering the receiver When the provider has a webhook API, provision the receiver programmatically in the `events.setup` block. StackOne runs its phases against the provider: `creation` (required) when events are enabled on a Connector Profile, `deletion` (required) when they are removed, and an optional `activation` step in between. Each phase is a list of ordinary `request` steps. StackOne threads two values through these steps: - `${inputs.callbackUrl}` — the StackOne receiver URL the provider should post events to. Map it into the create request. - `${inputs.remoteId}` — the id of the webhook the provider created, read from `creation.result`. `activation` and `deletion` reference it to target that webhook. ```yaml # {provider}.connector.s1.yaml events: setup: creation: steps: - stepId: create_webhook stepFunction: functionName: request parameters: url: /webhooks method: post args: - { name: url, value: '${inputs.callbackUrl}', in: body } result: $.steps.create_webhook.output.data.id # StackOne stores this as ${inputs.remoteId} deletion: steps: - stepId: delete_webhook stepFunction: functionName: request parameters: url: '/webhooks/${inputs.remoteId}' method: delete ``` If the provider has no webhook API, leave `setup` out and register manually with a [Native Webhook URL](#native-webhook-url). ## Native Webhook URL When a provider is configured manually, expose a Native Webhook URL on the connector profile by adding a field to your authentication config: ```yaml - key: nativeWebhookUrl label: Native Webhook URL value: "{{webhookEventsUrl(webhooks_url, orgId, projectSecureId, connectorProfileId, external_trigger_token)}}" description: Paste this into the provider's webhook settings. ``` The user copies this URL into the provider's own webhook configuration, guided by the steps you define in `events.guides.setup`. ## Related Every field of the events block, with examples. # Rendering Guides Source: https://docs.stackone.com/connector-building/rendering-guides Fetch a connector's guides from the API and render them in your own product. Guides live in the connector YAML under `support.guides`, so they ship and version with the connector instead of going stale in a separate docs site while the connector changes. Fetch them from the API to render in your own product. The schema: sections, steps, warnings, images, and scope filtering. ## Fetch the guides Guides come back from `GET /actions` when you ask for them: ```bash curl -X GET "https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=[provider]" \ -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)" ``` | Parameter | Description | |-----------|-------------| | `include=authentication_guides` | Returns `support.guides` for each authentication method | | `include=event_guides` | Returns the event guides from `events.guides` | | `include=action_details` | Returns extended action metadata | | `filter[connectors]` | Restrict to one connector key, such as `filter[connectors]=bamboohr` | | `page_size` | Results per page | | `next` | Pagination cursor from the previous response | Full parameter and response reference. ## Response shape Guides are nested per authentication method, since each method needs different instructions: ```json { "data": [ { "key": "your_provider", "name": "Your Provider", "authentication": [ { "type": "custom", "label": "API Key", "key": "api_key", "configFields": [ { "key": "apiKey", "label": "API Key", "type": "password", "required": true } ], "support": { "guides": { "config": { "warning": "Admin access required to generate an API key.", "sections": [ { "title": "Generating an API Key", "content": "Generate an API key from your admin dashboard.", "steps": [ { "title": "Sign in and open API settings", "content": "Sign in to your Provider account.", "list": [ "Click **Settings** in the top navigation", "Select **API** from the sidebar", "Click **Create API Key**" ] } ] } ] } } } } ], "actions": [ { "id": "your_provider_list_employees", "label": "List Employees", "required_scopes": ["employees:read"] } ] } ], "next": null } ``` ## Render in your own UI The shape is small enough to type by hand. `title` and `content` are always present; everything else is optional: ```typescript interface GuideImage { src: string; alt: string; } interface GuideStep { title: string; content: string; list?: string[]; image?: GuideImage; /** Space-separated scope names, not an array */ applicableScopes?: string; /** Render badges for the actions these scopes unlock */ displayScopes?: boolean; } interface GuideSection { title: string; content: string; list?: string[]; image?: GuideImage; steps?: GuideStep[]; applicableScopes?: string; } interface AuthGuides { config?: { warning?: string; sections: GuideSection[] }; setup?: { warning?: string; sections: GuideSection[] }; } async function fetchConnectorGuides( connectorKey: string, apiKey: string, authMethodKey?: string, ): Promise { const authHeader = Buffer.from(`${apiKey}:`).toString("base64"); const response = await fetch( `https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=${connectorKey}`, { headers: { Authorization: `Basic ${authHeader}` } }, ); const { data } = await response.json(); const connector = data?.find((c: any) => c.key === connectorKey); if (!connector) { throw new Error(`Connector "${connectorKey}" not found`); } const auth = authMethodKey ? connector.authentication?.find((a: any) => a.key === authMethodKey) : connector.authentication?.[0]; return auth?.support?.guides ?? {}; } ``` In the browser, swap `Buffer.from(...)` for `btoa(`${apiKey}:`)`. `content` and `list` items contain markdown: links, bold for UI labels, backticks for URLs and values. Render them through a markdown component such as `react-markdown` and sanitize the output. Building HTML strings by hand and injecting them with `dangerouslySetInnerHTML` puts provider-authored text straight into your DOM. ```tsx import ReactMarkdown from "react-markdown"; function Section({ section }: { section: GuideSection }) { return (

{section.title}

{section.content} {section.list && (

{item}

)} {section.image && {section.image.alt}

} {section.steps?.map((step) => (

{step.title}

{step.content}

))}

); } ``` `applicableScopes` marks a section or step as relevant only to certain scopes, so a read-only integration isn't told to grant write access. It's a **space-separated string**, so split it before comparing: ```typescript function appliesTo(scopes: string | undefined, selected: string[]): boolean { if (!scopes) { return true; } return scopes.split(/\s+/).some((scope) => selected.includes(scope)); } const visible = sections.filter((section) => appliesTo(section.applicableScopes, selected)); ``` A section with no `applicableScopes` always shows. Steps carry the same field, so filter them the same way. ## Related The guide, section, and step fields in full. # Connector Versioning Source: https://docs.stackone.com/connector-building/connector-versioning Connector versioning ensures your linked accounts aren't affected by breaking changes until you're ready to adopt them. Pin each connector profile to a version and upgrade on your own schedule. Connectors are versioned with semver (`major.minor.patch`). Each connector profile resolves to a specific connector version when linked accounts make requests. Because each connector profile pins independently, you can test a new version against a staging profile before rolling it out to production, and migrate different customer groups to a new connector version at their own pace. ## Version selection By default, a connector profile resolves to: 1. The latest **custom** version of the connector, if one exists in your project. 2. Otherwise, the latest **StackOne** version. Custom connectors are connectors you [build and publish yourself](/connector-building/overview). If you only use StackOne's built-in connectors then point 1 does not apply. Custom connectors always take precedence over StackOne connectors with the same key, including when version numbers match. Publishing a new StackOne version does not override a custom connector with the same key. ### Pinning a version When creating or editing a connector profile, you can override the default and pin the version to: - **Latest StackOne** - always resolves to the latest published StackOne version, ignoring custom versions. Use this when you rely on StackOne's managed updates. - **Latest custom** - always resolves to the latest published custom version. Use this when you maintain your own connector and want deploys to roll out automatically. - **A specific version** - pin to an exact version number (StackOne or custom). Use this in production when you need full control over when updates apply. When pinned to a "latest" option, existing linked accounts automatically pick up new versions as they are published. When pinned to a specific version, linked accounts stay on that version until the pin is changed. The accepted pin formats are: | Pin | Resolves to | Auto-updates | |-----|-------------|--------------| | `latest` | Newest version (custom if exists, else StackOne) | Yes | | `1.x.x` | Latest minor + patch within major version 1 | Yes, within major 1 | | `1.2.x` | Latest patch within 1.2.* | Yes, patch only | | `1.2.0` | Exactly 1.2.0, never changes | No | | *(no pin)* | Custom latest if exists, else StackOne latest | Yes | Note: npm-style caret (`^1.2.0`) and tilde (`~1.2`) are not accepted. In the dashboard, the pin is the profile's **Update strategy**: always use the latest, or pin to a major, minor, or exact version. Set it in the **Create Profile** panel, or later from **Edit profile** in the menu on the profile's card. Or set it via the API: ```bash curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " \ -H "Content-Type: application/json" \ -d '{"pinned_version": "1.x.x"}' ``` To revert to the default resolution (custom latest, then StackOne latest): ```bash curl -X DELETE https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " ``` Pin production connector profiles to a major version wildcard, for example `1.x.x` rather than `latest`. A new major version can include authentication or scope changes that break existing linked accounts if they upgrade without warning. With `1.x.x`, you pick up bug fixes and new optional fields automatically while keeping control over breaking upgrades. ## Breaking changes and version updates This is how StackOne classifies changes when versioning its built-in connectors. Understanding these categories helps you interpret what a version bump means and whether it requires action on your end. Publishing a new connector version does not invalidate existing linked accounts. Accounts continue to work and automatically pick up the new version on the next request, provided the connector profile is on an auto-updating pin (`latest`, `1.x.x`, or `1.2.x`). Accounts pinned to a specific version remain on that version until the pin is manually updated. Any change that is not backwards compatible is released as a new **major** version. This includes, but is not limited to: - **Authentication changes** - switching authentication type, adding required scopes, or changing required credential fields. These require linked accounts to re-authenticate. - **Response shape changes** - renaming or removing fields, changing field types, or restructuring nested objects in an action's response. - **Request shape changes** - renaming or removing parameters, making optional parameters required, or changing accepted value types. - **Removed or renamed actions** - any action that callers may currently reference. - **Behavioral changes** - changes to pagination, filtering, error semantics, or default values that consumers may have relied on. | Version bump | Example change | Breaking for consumers | |--------------|----------------|------------------------| | Patch (`1.2.3 → 1.2.4`) | Bug fix, description update, internal refactor | No | | Minor (`1.2.3 → 1.3.0`) | New action, new optional parameter, new optional response field | No | | Major (`1.2.3 → 2.0.0`) | New authentication type or required scope, removed/renamed field, changed response shape, removed action | Yes | ## Versioning strategy When building custom connectors, you set your own versioning convention. The version number communicates what kind of migration work a change requires for anyone pinned to it. Auth-breaking changes — new OAuth flow, required scopes, or changed credential fields — require end users to reauthenticate. These almost always warrant a major version bump. The migration involves creating a new connector profile and prompting users through a new connect flow. A common approach: | Level | Use for | Who needs to act | |-------|---------|-----------------| | **Major** | Auth flow or scope changes | Your end users: they reauthenticate through the new flow | | **Minor** | New actions, new optional fields or parameters | Nobody: existing code keeps working | | **Patch** | Bug fixes, internal refactors | Nobody: existing code keeps working | The version level is your contract with yourself. Pick the convention that makes your migration work predictable. ## Checking available versions To see every published version for a connector profile and which one is currently active: ```bash curl https://api.stackone.com/connector_profiles/{connector_profile_id}/versions \ -H "Authorization: Basic " ``` ```json [ { "version": "1.0.0", "pinned": false, "builtin": true, "owner": "stackone" }, { "version": "1.2.0", "pinned": true, "builtin": true, "owner": "stackone" } ] ``` The `pinned: true` entry is the version currently serving requests for this connector profile. Note that the response shows the resolved exact version (`1.2.0`), not the pin format (`1.2.x`). The pin itself is set on the connector profile, not returned here. ## Migrating to a new version ### Non-breaking releases For releases your team has classified as non-breaking (patch fixes, new optional fields, additive changes), connector profiles pinned to `latest`, a major wildcard (`1.x.x`), or a minor wildcard (`1.2.x`) will pick up the new version automatically on the next request. No action required. If your connector profile is pinned to an exact version (e.g. `1.2.0`), it won't move until you update the pin manually: ```bash curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \ -H "Authorization: Basic " \ -H "Content-Type: application/json" \ -d '{"pinned_version": "1.2.1"}' ``` ### Auth/permissions breaking changes When a connector introduces a new OAuth flow or required scope, existing accounts stay on their current connector profile until you explicitly migrate them. This is a coordinated rollout rather than a silent upgrade. The existing connector profile and all accounts on it are untouched. This new profile handles the updated authentication flow. Call [`GET /v2/connector_profiles`](/platform/api-reference/v2/connector-profiles/list-connector-profiles) and read the `id` of the profile you created. Pass that value as `connector_profile_id` when creating connect sessions. (`integration_id` is a deprecated alias for the same field in some payloads.) Pass `connector_profile_id` explicitly when creating connect sessions. This routes the session to the new profile. Alternatively, make the new connector profile the project default and omit `connector_profile_id`. See [Target a specific connector profile](/embed/connect-session#target-a-specific-connector-profile) for the request format. Send an email, in-app notification, or modal prompting users to reconnect through the Integration Hub. The connect flow uses the new session token, which routes to the new connector profile. You can identify which accounts still need migration by checking which remain associated with the old connector profile. When a user completes the new authentication flow, their linked account moves to the new connector profile. Subsequent requests resolve against the new major version. The recommended migration pattern is a staging connector profile pinned to the new version. Test your integration against it before updating the production profile. Each connector profile pins independently, so there's no coupling between environments. ## Immutable versioning Immutable versioning controls whether published versions can be overwritten. It is **enabled by default**. The setting can be found in **Project Settings → General → Danger Zone**. Immutable Versioning toggle enabled in the Danger Zone tab of Project Settings

Immutable Versioning toggle enabled in the Danger Zone tab of Project Settings

- **Enabled** (default) - Each version number is locked once published. Subsequent publishes must use a new version number. Use this to guarantee that linked accounts on a pinned version see exactly the connector that was originally published. - **Disabled** - Republishing the same version number is allowed when pushing with the [CLI's](/connector-building/stackone-cli) `--force` flag (`stackone push --force`). Without `--force`, the CLI still rejects overwrites. Linked accounts resolving to an overwritten version will pick up the new content on the next request. When immutable versioning is enabled, the `--force` flag has no effect - overwrites are rejected regardless. Enable immutable versioning in production projects to prevent accidental overwrites of a version that linked accounts depend on. Disable it in development projects where iterating on a version without bumping the number is convenient. # GitHub CI/CD Source: https://docs.stackone.com/connector-building/github-ci-cd Validate and publish connectors automatically with GitHub Actions. Publishing from a Git pipeline instead of your own machine means every change is validated on the pull request, and merging is what pushes the connector to a project. It also gives you one API key per environment rather than one on each developer's laptop. CI/CD workflow: Edit YAML → Validate → Push → GitHub Actions → StackOne Projects (dev/staging/prod)

CI/CD workflow: Edit YAML → Validate → Push → GitHub Actions → StackOne Projects (dev/staging/prod)

The pipeline is yours to shape: - **Single project**: push to one project from any branch - **Multi-environment**: route branches to separate projects, such as develop to dev and main to production - **Custom**: your own branch strategy and approval gates ## Repository structure Organize the repository however suits your team. What matters is that the connector directories keep the layout described in [File Structure](/connector-yaml-reference/file-structure), so `validate` and `push` can be pointed at a single parent directory: ``` custom-connectors/ ├── .github/ │ └── workflows/ │ └── deploy.yml # CI/CD pipeline ├── connectors/ │ └── {provider}/ │ ├── {provider}.connector.s1.yaml │ └── {provider}.{resource}.s1.partial.yaml └── README.md ``` ## Add your API key as a secret In the repository, go to **Settings → Secrets and variables → Actions** and add the API key for the project you're publishing to: | Secret | Description | |--------|-------------| | `STACKONE_API_KEY` | API key for your StackOne project | The key needs the `connectors:write` scope to push. See [API Keys](/embed/api-keys) for generating one. ## Create the workflow file Create `.github/workflows/deploy.yml`. Both examples validate on pull requests and publish only on a push to a release branch: ```yaml name: Validate and Deploy Connectors on: push: branches: [main] paths: - 'connectors/**' pull_request: branches: [main] paths: - 'connectors/**' jobs: validate-and-deploy: name: Validate and Deploy runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install StackOne CLI run: npm install -g @stackone/cli - name: Validate connectors run: stackone validate connectors/ - name: Check agent skills are in sync run: stackone agent sync --check - name: Deploy if: github.event_name == 'push' env: STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }} run: stackone push connectors/ --api-key $STACKONE_API_KEY ``` For separate dev, staging, and production projects, add one secret per project: | Secret | Description | |--------|-------------| | `STACKONE_API_KEY_DEV` | Development project | | `STACKONE_API_KEY_STAGING` | Staging project | | `STACKONE_API_KEY_PROD` | Production project | ```yaml name: Validate and Deploy Connectors on: push: branches: [develop, staging, main] paths: - 'connectors/**' pull_request: branches: [develop, staging, main] paths: - 'connectors/**' jobs: validate: name: Validate Connectors runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @stackone/cli - run: stackone validate connectors/ - run: stackone agent sync --check deploy-dev: needs: validate if: github.ref == 'refs/heads/develop' && github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @stackone/cli - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_DEV }} deploy-staging: needs: validate if: github.ref == 'refs/heads/staging' && github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @stackone/cli - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_STAGING }} deploy-prod: needs: validate if: github.ref == 'refs/heads/main' && github.event_name == 'push' runs-on: ubuntu-latest environment: production # Optional: require manual approval steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @stackone/cli - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_PROD }} ``` `stackone agent sync --check` compares the `.claude/skills/` and `CLAUDE.md` guide committed in the repository against the ones bundled with the installed CLI, and exits non-zero if they differ. It needs no credentials. Because the workflow installs the latest CLI, a new CLI release that ships updated skills will fail this step until someone runs `stackone agent sync` and commits the result. Pin the CLI version in the workflow if you'd rather choose when that happens. ## Test after deploying A published connector needs a linked account before you can call anything against it: Open your custom connector in the project's [Connectors](https://app.stackone.com/connectors) page and click **Add Profile**. Select the actions you want exposed, click **Continue**, fill in authentication, and click **Create Profile**. Connector profiles, authentication, and scoping. Create a linked account through the [Hub](/embed/account-linking/overview) or the API. Select the account in the [Playground](/embed/call-actions/troubleshooting/playground) and try the actions in natural language, or run one directly: ```bash stackone run \ --connector connectors/[provider]/[provider].connector.s1.yaml \ --account-id [account-id] \ --profile [profile-label] \ --action-id [action-id] ``` The profile's API key needs the `credentials:read` scope to use a linked account's stored credentials. Push updates as you refine the connector. Existing linked accounts are unaffected until you move them, which is covered in [Connector Versioning](/connector-building/connector-versioning). ## Common errors - Check YAML indentation, which must be 2 spaces rather than tabs - Partial files start with `-`, not `actions:` - Every `$ref` matches an actual file name, which matters on case-sensitive CI runners even when it works on macOS - Run `stackone validate connectors/` locally against the same parent directory the workflow uses - The secret name in the workflow matches the one in repository settings - The API key carries the `connectors:write` scope - The key belongs to the project you intended to publish to, not another environment - The file sits in `.github/workflows/` - Branch names in `on.push.branches` match your actual branches - The `paths` filter covers the files you changed. Editing only a workflow or README will not match `connectors/**` ## Next steps The build and debug loop that comes before publishing. Release new versions without breaking existing linked accounts. Full reference for validate, run, and push. # StackOne CLI Source: https://docs.stackone.com/connector-building/stackone-cli StackOne CLI commands for building, validating, testing, and deploying connectors The StackOne CLI (`@stackone/cli`) provides commands for building, validating, testing, and deploying custom connectors. Complete CLI documentation on npm ## Installation ```bash npm install -g @stackone/cli ``` --- ## Command Reference ### Agent Commands Set up the agent, and the MCP server that gives an AI coding assistant StackOne's tools. | Command | Description | |---------|-------------| | `stackone agent setup --local` | Authenticate, write `.mcp.json`, and install the connector-building skills into `.claude/` plus a guide block in `CLAUDE.md` | | `stackone agent setup --global` | Authenticate and register the MCP server in `~/.claude.json`. No skills or guide | | `stackone agent skills` | List the bundled skills | | `stackone agent sync` | Refresh this project's skills and guide | | `stackone agent cleanup` | Remove stored credentials and configuration | ```bash # In a connector repo: auth + MCP server + skills + CLAUDE.md guide stackone agent setup --local # Install into a directory other than the current one stackone agent setup --local --path ~/code/custom-connectors # Auth + MCP server only, for projects that aren't connector repos stackone agent setup --global # Remove all API keys and credentials stackone agent cleanup ``` The API key is stored in `~/.stackone/agent-config.json` either way. The MCP server entry goes to `~/.claude.json` for `--global`, or the project's `.mcp.json` for `--local`. Use `--local` in the repo where you build connectors, since it's the only mode that installs the skills and the guide. It authenticates you at the same time, so `--global` is not a prerequisite. Passing neither flag prompts for the mode. #### Skills `agent setup --local` installs a set of connector-building skills into `.claude/skills/`. List what you have, and the subset recommended for a mode: ```bash stackone agent skills stackone agent skills --mode build ``` After upgrading the CLI, refresh the copies in your project: ```bash stackone agent sync # Report drift and exit non-zero instead of writing, for CI stackone agent sync --check ``` --- ### Connector Development | Command | Description | |---------|-------------| | `stackone validate ` | Validate connector YAML syntax and structure | | `stackone run` | Execute a connector action locally for testing | ```bash # Validate with watch mode stackone validate ./my-connector/ --watch # Run an action with local credentials stackone run \ --connector my-connector.connector.s1.yaml \ --account account.json \ --credentials credentials.json \ --action-id list_employees \ --debug # Run with parameters stackone run \ --connector my-connector.connector.s1.yaml \ --account account.json \ --credentials credentials.json \ --action-id get_employee \ --params params.json # Run custom action code (for testing action definitions) stackone run \ --connector my-connector.connector.s1.yaml \ --account-id acme-corp-provider \ --action ./custom-action.yaml # Save output to file stackone run \ --connector my-connector.connector.s1.yaml \ --account-id acme-corp-provider \ --action-id list_employees \ --output-file results.json ``` **Test file formats:** ```json account.json { "environment": "production", "provider": "provider" } ``` ```json credentials.json (API Key) { "apiKey": "your_api_key" } ``` ```json credentials.json (OAuth2) { "accessToken": "token", "refreshToken": "refresh_token", "clientId": "client_id", "clientSecret": "client_secret" } ``` ```json params.json { "path": { "id": "emp_123" }, "queryParams": { "include": "manager" } } ``` **Params structure:** each top-level key corresponds to an input's `in:` location in the action's YAML. Put every value under the key that matches where the input is sent. | Key | Inputs it carries | |-----|-------------------| | `path` | `in: path`: URL path parameters | | `queryParams` | `in: query` | | `header` | `in: headers` (singular `header`) | | `body` | `in: body` | You can pass the same object inline instead of a file: ```bash stackone run \ --connector connectors/[provider]/[provider].connector.s1.yaml \ --account-id [account-id] \ --action-id get_employee \ --params '{"path": {"id": "emp_123"}, "queryParams": {"include": "manager"}}' ``` **Faster iteration:** Once your connector is pushed or an account is already linked, skip the credentials file and use `--account-id` instead: ```bash stackone run \ --connector my-connector.connector.s1.yaml \ --account-id acme-corp-provider \ --action-id list_employees ``` This uses stored credentials from the linked account, making it easier to iterate on action logic without managing local credential files. **Note:** Using `--account-id` requires an API key with `connectors:read` scope. ### Deployment Deployment commands require an API key with **Connectors** scopes. See [API Keys](/embed/api-keys) to generate one. | Command | Description | Required Scope | |---------|-------------|----------------| | `stackone push ` | Upload connector to StackOne registry | `connectors:write` | | `stackone pull` | Download connector files to local filesystem | `connectors:read` | | `stackone drop ` | Delete a connector version from registry | `connectors:write` | | `stackone get` | Retrieve connector configuration (YAML or JSON output) | `connectors:read` | ```bash # Push using saved profile stackone push ./my-connector/ --profile prod # Push with API key directly stackone push ./my-connector/ --api-key v1.eu1.xxxxx # Pull connector files (saves to ./connectors/my_provider/ by default) stackone pull --connector my_provider --profile prod # Pull a specific version to a different directory stackone pull --connector my_provider@1.0.0 --profile prod --output-path ./custom-connectors # Get connector config as YAML (default) stackone get --connector my_provider # Get connector config from a linked account stackone get --account-id acme-corp-provider --format json --output-file config.json ``` --- ### Configuration | Command | Description | |---------|-------------| | `stackone init` | Configure authentication profiles interactively | | `stackone version` | Show version with update check | | `stackone update` | Update CLI to latest version | ```bash # Interactive setup (prompts for profile name and API key) stackone init # Setup for different environments stackone init --env staging stackone init --env production # Check version and available updates stackone version # Update to latest version stackone update ``` --- ## Environment Variables | Variable | Description | |----------|-------------| | `STACKONE_AGENT_MCP_TOKEN` | MCP server access token (set by `agent setup`) | API keys are passed via `--api-key` flag or stored in your profile configuration, not as environment variables. --- ## Next Steps Build a connector from scratch with these commands Automated validation and publishing with GitHub Actions # Connector YAML Reference Source: https://docs.stackone.com/connector-yaml-reference/overview YAML Schema reference for connector configurations Custom connector building is only available on certain plans. Each custom connector takes up one of your plan's slots. See [plans and pricing](https://www.stackone.com/pricing/). StackOne connectors are defined in YAML. The same schema powers every pre-built connector, and you can use it to build your own. If you're new to connectors, start with [Build your first connector](/guides/connector-engine/building-first-connector) and [Connector structure](/connector-yaml-reference/file-structure). How a connector's files are organized, from the main file to resource partials. Every top-level connector property: info, baseUrl, authentication, actions, events, and more. The step functions you compose inside action and event setup steps. JSONPath, JEXL, and string interpolation used throughout the schema. # File Structure Source: https://docs.stackone.com/connector-yaml-reference/file-structure How to organize connector files using partial files and suggested naming conventions. Connectors are organized into a **main connector file** and, optionally, **partial files**. Partial files can be used to split large connectors up into more manageable chunks for maintenance and are consumed in the StackOne platform as if it were a single configuration file. ## Best practices For maintaining connectors for development, use the directory structure below: ``` connectors/{provider}/ ├── {provider}.connector.s1.yaml # Main connector file (authentication, metadata) ├── {provider}.{resourceA}.s1.partial.yaml # Partial file (actions grouped by resourceA) ├── {provider}.{resourceB}.s1.partial.yaml # Partial file (actions grouped by resourceB) └── {provider}.events.s1.partial.yaml # Partial file (event handlers - if available) ``` ### Main connector file The main connector file defines the top-level properties (see [YAML Schema](/connector-yaml-reference/yaml-schema/overview)): connector metadata, authentication, and an `actions` block (plus an `events` block for webhooks) that reference the partial files. Partial files are referenced in the main file by the filename without the `.s1.partial.yaml` extension. Parital files must be within the same folder as the main connector file. ```yaml # acme.connector.s1.yaml StackOne: 1.0.0 ... actions: - $ref: acme.employees # references acme.employees.s1.partial.yaml - $ref: acme.departments # references acme.departments.s1.partial.yaml events: setup: {...} router: {...} externalAccountIdExtractor: {...} actions: - $ref: acme.events # references acme.events.s1.partial.yaml ``` Add references in alphabetical order for readability. ### Partial files Each partial file is a group of actions, e.g. grouped per resource. ```yaml # acme.employees.s1.partial.yaml - actionId: list_employees ... - actionId: get_employee ... ``` ```yaml # acme.departments.s1.partial.yaml - actionId: list_departments ... - actionId: get_department ... ``` Event handlers are grouped the same way: ```yaml # acme.events.s1.partial.yaml - actionId: employee_created actionType: event ... - actionId: employee_updated actionType: event ... ``` ## Related Full YAML schema for building connectors with field tables and examples. # YAML Schema Source: https://docs.stackone.com/connector-yaml-reference/yaml-schema/overview Complete reference for all connector YAML properties with examples and impact analysis. ## Top-level structure ```yaml StackOne: 1.0.0 actions: [ ... ] authentication: [ ... ] baseUrl: 'https://api.provider.com' concurrency: { ... } documentation: { ... } events: { ... } forkedFrom: acme_hris info: { ... } mcp: { ... } rateLimit: { ... } releaseStage: ga resources: 'https://api.provider.com/docs' scopeDefinitions: { ... } ```

Field	Description	Type	Required
`StackOne`	Connector schema version, set to `1.0.0`.	string	Yes
[`actions`](#actions)	Actions the connector exposes.	object[]	No
[`authentication`](#authentication)	Authentication methods the connector supports.	object[]	No
[`baseUrl`](#baseurl)	Root URL for all API requests. Supports expressions.	string	Yes
[`concurrency`](#concurrency)	Request concurrency configuration for the connector.	object	No
[`documentation`](#documentation)	External documentation links for the connector.	object	No
[`events`](#events)	Event and webhook configuration for the connector.	object	No
`forkedFrom`	Key of the connector this one was forked from. Not currently in use.	string	No
[`info`](#info)	Connector metadata.	object	Yes
[`mcp`](#mcp)	MCP-specific configuration for the connector.	object	No
[`rateLimit`](#ratelimit)	Request rate-limit configuration for the connector.	object	No
`releaseStage`	Default maturity level inherited by actions, events and authentication methods that do not declare their own. The stage of the connector itself is computed from theirs, never authored here. Allowed: `preview`, `beta`, `ga`, `deprecated`, `internal`	enum	No
`resources`	Source of information for the connector, usually a URL to the provider's documentation.	string	No
[`scopeDefinitions`](#scopedefinitions)	Requirements actions can depend on, keyed by name, such as OAuth scopes, pricing tiers, or feature flags.	object	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaOverview path="/" */} ## actions The operations the connector exposes, each with inputs, steps, and a result. See [actions](/connector-yaml-reference/yaml-schema/actions). ## authentication An array of authentication methods (OAuth 2.0, custom/API key, and others). See [authentication](/connector-yaml-reference/yaml-schema/authentication). ## baseUrl **Examples** ```yaml # Static URL baseUrl: 'https://api.bamboohr.com/api/gateway.php' # Dynamic URL with credentials: baseUrl: 'https://api.bamboohr.com/api/gateway.php/${credentials.subdomain}/v1' ``` Individual actions can override baseUrl in their step parameters. ## concurrency Request concurrency configuration for the connector.

Field	Description	Type	Required
`mainMaxConcurrency`	Maximum number of concurrent in-flight requests per linked account.	number	Yes
[`subPools`](#concurrency-subpools)	Per-URL-pattern concurrency overrides.	object[]	No

Per-URL-pattern concurrency overrides.

Field	Description	Type	Required
`maxConcurrency`	Maximum concurrent requests for the matched URLs.	number	Yes
`subPoolKey`	Identifier for this concurrency sub-pool.	string	Yes
`urlPattern`	URL pattern the sub-pool's limit applies to.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/concurrency" */} **Examples** ```yaml concurrency: mainMaxConcurrency: 5 subPools: - subPoolKey: reports urlPattern: '/reports' maxConcurrency: 1 ``` ## documentation External documentation links for the connector.

Field	Description	Type	Required
[`references`](#documentation-references)	External documentation links.	object[]	Yes

External documentation links.

Field	Description	Type	Required
`description`	Explains what the reference covers.	string	No
`title`	Link text for the reference.	string	Yes
`url`	URL of the referenced document.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/documentation" */} **Examples** ```yaml documentation: references: - title: API reference url: https://api.acme.com/docs description: Full REST API documentation. ``` ## events Webhook and event configuration for the connector. See [events](/connector-yaml-reference/yaml-schema/events). ## info Connector metadata.

Field	Description	Type	Required
[`assets`](#info-assets)	Visual assets for the connector.	object	Yes
[`changelog`](#info-changelog)	Description of what changed in this version.	object	No
`description`	Brief one-line summary of the connector.	string	Yes
`details`	Extended description of capabilities and limitations.	string	No
`key`	Unique lowercase identifier for the connector.	string	Yes
`title`	Human-readable provider name shown in Hub and Dashboard.	string	Yes
`version`	Connector version following semantic versioning.	string	Yes

Visual assets for the connector.

Field	Description	Type	Required
`icon`	URL to the provider logo.	string	Yes

Description of what changed in this version.

Field	Description	Type	Required
`labels`	Tags categorizing the changelog entry for filtering.	string[]	No
`summary`	Human-readable summary of the changes in this version.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/info" */} ### info.assets.icon Requirements: - 24x24 pixels minimum - SVG or PNG format - Transparent background preferred - Hosted on HTTPS ### info.description Best practices: - Keep under 200 characters - Mention key capabilities - Include category context (HRIS, CRM, etc.) ### info.version See [Connector Versioning](/connector-building/connector-versioning) **Examples** ```yaml info: title: Acme HRIS key: acme_hris version: 1.0.0 description: HRIS connector for Acme covering employees, departments, and time-off. assets: icon: https://stackone-logos.com/api/acme/filled/png ``` ## mcp MCP-specific configuration for the connector.

Field	Description	Type	Required
`instructions`	Guidance text surfaced to MCP clients (max 2000 characters).	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/mcp" */} ## rateLimit The runtime tracks requests per linked account and throttles when limits are reached. Requests exceeding the limit are queued and retried with exponential backoff. Request rate-limit configuration for the connector.

Field	Description	Type	Required
`mainRatelimit`	Maximum requests per second for each linked account, across all of the connector's endpoints.	number	Yes
[`mappedRateLimitErrors`](#ratelimit-mappedratelimiterrors)	Provider responses that should be treated as rate-limit signals.	object[]	No
[`subPools`](#ratelimit-subpools)	Per-URL-pattern rate limit overrides.	object[]	No

Provider responses that should be treated as rate-limit signals.

Field	Description	Type	Required
`errorMessage`	Provider error message identifying a rate-limit error.	string	Yes
`errorMessagePath`	Path to the error message in the response body.	string	No
`errorStatus`	HTTP status code indicating a rate-limit error.	number	Yes
`retryAfterPath`	Path to the retry-after value within the response headers, not the body.	string	No
`retryAfterUnit`	Unit the retry-after value is expressed in. Allowed: `seconds`, `milliseconds`, `date`	enum	No
`retryAfterValue`	Fixed delay to wait before retrying.	number	No

Per-URL-pattern rate limit overrides.

Field	Description	Type	Required
`rateLimit`	Maximum requests per second for the matched URLs.	number	Yes
`subPoolKey`	Identifier for this rate-limit sub-pool.	string	Yes
`urlPattern`	URL pattern the sub-pool's limit applies to.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/rateLimit" */} **Best practices** - Set slightly below provider’s documented limit - Check provider API docs for per-endpoint limits - Some providers have different limits for different endpoints **Examples** ```yaml rateLimit: mainRatelimit: 10 subPools: - subPoolKey: search urlPattern: '/search' rateLimit: 2 mappedRateLimitErrors: - errorStatus: 429 errorMessage: Too Many Requests retryAfterPath: "$['retry-after']" retryAfterUnit: seconds ``` ## scopeDefinitions Requirements actions can depend on, keyed by name, such as OAuth scopes, pricing tiers, or feature flags.

Field	Description	Type	Required
`description`	Explains what this scope grants.	string	Yes
`includes`	Another scope this scope implies.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/scopeDefinitions" */} **Examples** ```yaml scopeDefinitions: employees:read: description: Read employee data employees:write: description: Create and update employee records includes: employees:read ``` ## Related How connector files and partials are organized. The step functions actions are built from. # Authentication Source: https://docs.stackone.com/connector-yaml-reference/yaml-schema/authentication Field reference for a connector's authentication types. # Structure Multiple authentication methods per connector are allowed. ```yaml authentication: # Authentication using OAuth - oauth2: type: oauth2 label: OAuth 2.0 # ...remaining oauth2 fields # Authentication using API key - api_key: type: custom label: API Key # ...remaining custom fields ``` # Properties Authentication methods the connector supports.

Field	Description	Type	Required
[`authorization`](#authorization)	Runtime authorization strategy applied to outgoing requests.	union	Yes
[`certificates`](#certificates)	Mutual-TLS certificates and keys for this method.	object	No
[`configFields`](#configfields)	Credentials the end-user enters when linking an account.	array	No
[`configNotices`](#confignotices)	Callouts shown while entering config fields.	object[]	No
[`environments`](#environments)	Deployment targets selectable for this method.	object[]	Yes
`grantType`	OAuth grant flow used to obtain tokens. Allowed: `authorization_code`, `client_credentials` Default: `authorization_code`	enum	No
`label`	Display name for this authentication method.	string	Yes
[`refreshAuthentication`](#refreshauthentication)	Configuration for refreshing expired credentials.	object	No
`releaseStage`	Maturity level of this authentication method. Defaults to the highest stage among the actions and events it can run. Allowed: `preview`, `beta`, `ga`, `deprecated`, `internal`	enum	No
`requiredScopes`	Scope names required by this authentication method. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
[`setupFields`](#setupfields)	Credentials entered when creating a Connector Profile.	array	No
[`setupNotices`](#setupnotices)	Callouts shown while entering setup fields.	object[]	No
[`support`](#support)	Help resources shown while connecting with this method.	object	No
[`testActions`](#testactions)	Actions run to validate a connection after authentication.	object[]	No
`type`	Selects the OAuth 2.0 authentication method.	string	Yes
[`authorizationFlow`](#authorizationflow)	MCP OAuth authorization flow; static credentials are used when omitted.	object	No
`serverUrl`	MCP server URL this authentication method connects to.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaOverview path="/properties/authentication" */} The variants share a common set of fields and are told apart by `type`. The `grantType` field selects the OAuth grant flow, either `authorization_code` (default) or `client_credentials`. ```yaml authentication: - oauth2: type: oauth2 label: OAuth 2.0 grantType: authorization_code authorization: { ... } environments: [ ... ] # ...remaining fields ``` The general-purpose method, for providers whose authentication doesn't fit `oauth2`, `oidc`, or `mcp`. ```yaml authentication: - api_key: type: custom label: API Key authorization: { ... } environments: [ ... ] # ...remaining fields ``` Runs the authorization-code flow using standard OpenID Connect discovery. ```yaml authentication: - oidc: type: oidc label: OpenID Connect authorization: { ... } environments: [ ... ] # ...remaining fields ``` Authenticates against a remote MCP server. The optional `authorizationFlow` field runs the MCP OAuth sequence when present, and falls back to static credentials like `custom` when omitted. ```yaml authentication: - mcp: type: mcp label: MCP Server authorizationFlow: clientRegistration: dcr scopes: [read, write] authorization: { ... } environments: [ ... ] # ...remaining fields ``` ## authorization Runtime authorization strategy applied to outgoing requests.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/authorization" */} When the `authorization` type is `oauth2`, the runtime runs the authorization-code flow: 1. The end-user clicks Connect in the StackOne Hub. 2. The runtime builds the authorization URL from `authorizationUrl` and `authorizationParams`. 3. The end-user signs in at the provider and grants access. 4. The provider redirects back to the callback URL with an authorization code. 5. The runtime exchanges that code for tokens at `tokenUrl`. 6. The tokens are stored as the Linked Account's credentials. **Examples** ```yaml authorization: type: none ``` ```yaml authorization: type: basic username: $.credentials.username password: $.credentials.password ``` ```yaml authorization: type: bearer token: $.credentials.accessToken ``` ```yaml authorization: type: oauth2 authorizationUrl: https://auth.provider.com/oauth2/authorize authorizationParams: response_type: code client_id: $.credentials.clientId redirect_uri: ${apiHostUri}/connect/oauth2/{provider}/callback scope: $.credentials.scopes tokenUrl: https://auth.provider.com/oauth2/token token: $.credentials.accessToken includeBearer: true ``` ## authorizationFlow MCP OAuth authorization flow; static credentials are used when omitted.

Field	Description	Type	Required
`clientRegistration`	Client registration mechanism used with the MCP server. Allowed: `cimd`, `dcr` Default: `cimd`	enum	Yes
`discovery`	Whether OAuth authorization-server metadata is discovered automatically. Default: `true`	boolean	Yes
`scopes`	OAuth scopes requested during the MCP authorization flow.	string[]	No
`serverUrl`	MCP server URL the connect flow authorizes against.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/3/properties/authorizationFlow" */} **Examples** ```yaml authorizationFlow: clientRegistration: dcr scopes: [read, write] ``` ## certificates Mutual-TLS certificates and keys for this method.

Field	Description	Type	Required
`certs`	Client certificates used for mutual-TLS.	string[]	No
`keys`	Private keys used for mutual-TLS.	string[]	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/certificates" */} **Examples** ```yaml configFields: - key: client_cert label: Client certificate (PEM) type: password required: true secret: true - key: client_key label: Client private key (PEM) type: password required: true secret: true certificates: certs: [client_cert] keys: [client_key] ``` ## configFields Credentials the end-user enters when linking an account.

Field	Description	Type	Required
`computed`	Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.	boolean	No
`description`	Helper text explaining what the user should enter.	string	No
`externalSystemAccountIdentifier`	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
`key`	Identifier the credential value is stored and referenced under.	string	Yes
`label`	Human-readable name shown for this field.	string	Yes
`placeholder`	Example value shown in the empty input to hint the expected format.	string	No
`readOnly`	Whether the field is displayed but cannot be edited by the user. Default: `false`	boolean	Yes
`required`	Whether the field must have a value. Default: `false`	boolean	Yes
`secret`	Encrypt the value at rest and mask it in the UI. Default: `false`	boolean	Yes
`tooltip`	Additional guidance shown on hover for this field.	string	No
`type`	Input control rendered for this credential field. Allowed: `text`, `password`, `text_area`	enum	Yes
[`validation`](#configfields-text-password-text-area-validation)	Client-side validation constraint applied to the entered value.	object	No
`value`	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

Client-side validation constraint applied to the entered value.

Field	Description	Type	Required
`errorMessage`	Message shown when the value fails the pattern or format check.	string	No
`format`	Named format the entered value must match, standing in for a common regular expression. Provide this or `pattern`, not both. Allowed: `email`, `url`, `uri`, `uuid`, `date`, `datetime`	enum	No
`pattern`	Regular expression the entered value must match. Provide this or `format`, not both.	string	No

Field	Description	Type	Required
`computed`	Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.	boolean	No
`description`	Helper text explaining what the user should enter.	string	No
`externalSystemAccountIdentifier`	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
`key`	Identifier the credential value is stored and referenced under.	string	Yes
`label`	Human-readable name shown for this field.	string	Yes
[`options`](#configfields-select-options)	Selectable choices offered for this field.	object[]	Yes
`placeholder`	Example value shown in the empty input to hint the expected format.	string	No
`readOnly`	Whether the field is displayed but cannot be edited by the user. Default: `false`	boolean	Yes
`required`	Whether the field must have a value. Default: `false`	boolean	Yes
`secret`	Encrypt the value at rest and mask it in the UI. Default: `false`	boolean	Yes
`tooltip`	Additional guidance shown on hover for this field.	string	No
`type`	Input control rendered for this credential field.	string	Yes
`value`	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

Selectable choices offered for this field.

Field	Description	Type	Required
`label`	Human-readable text shown for this option.	string	Yes
`value`	Value stored when this option is selected.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/configFields/items" */} **Examples** ```yaml configFields: - key: subdomain label: Subdomain type: text required: true placeholder: acme-corp - key: client_id label: Client ID type: text required: true - key: client_secret label: Client Secret type: password required: true secret: true - key: region label: Region type: select required: true options: - { value: us, label: United States } - { value: eu, label: European Union } ``` ## configNotices Callouts shown while entering config fields.

Field	Description	Type	Required
`anchor`	Field key the notice is shown above. Only valid when position is top.	string	No
`description`	Text shown in the notice.	string	Yes
`key`	Identifier for the notice.	string	Yes
`position`	Whether the notice appears above or below the fields. Allowed: `top`, `bottom` Default: `top`	enum	Yes
`type`	Visual style of the notice. Allowed: `warning`, `info` Default: `info`	enum	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/configNotices/items" */} **Examples** ```yaml configNotices: - key: sandbox_warning type: warning description: Use your sandbox credentials while testing. position: top anchor: client_id ``` ## environments Deployment targets selectable for this method.

Field	Description	Type	Required
`key`	Identifier stored for the selected environment.	string	Yes
`name`	Human-readable environment name.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/environments/items" */} **Examples** ```yaml environments: - key: production name: Production - key: sandbox name: Sandbox ``` ## refreshAuthentication Configuration for refreshing expired credentials.

Field	Description	Type	Required
[`action`](#refreshauthentication-action)	Action executed to refresh the credentials.	object	Yes
`schedule`	Cron expression for proactively refreshing credentials.	string	No

Action executed to refresh the credentials. Same fields as [actions](/connector-yaml-reference/yaml-schema/actions). {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/refreshAuthentication" */} The initial OAuth exchange stores the provider's refresh token in the Linked Account's credentials. `refreshAuthentication` then keeps the access token current: 1. On the `schedule` cron, the runtime runs the `refresh_token` action. 2. The action sends the stored refresh token to the provider's token endpoint. 3. The provider returns a new access token, and sometimes a new refresh token. 4. The returned tokens replace the Linked Account's credentials. Set `schedule` to fire before the access token expires, so requests never use a stale token. **Examples** ```yaml refreshAuthentication: schedule: '*/50 * * * *' # every 50 minutes (10 min before 60 min token expiry) action: actionId: refresh_oauth_token actionType: refresh_token label: Refresh OAuth token description: Exchange refresh_token for a new access_token. steps: - stepId: refresh description: POST to the token endpoint. stepFunction: functionName: request version: v1 parameters: url: https://auth.provider.com/oauth/token method: post args: - { name: grant_type, value: refresh_token, in: body } - { name: refresh_token, value: '${credentials.refresh_token}', in: body } - { name: client_id, value: '${credentials.client_id}', in: body } - { name: client_secret, value: '${credentials.client_secret}', in: body } ``` ## setupFields Credentials entered when creating a Connector Profile.

Field	Description	Type	Required
`computed`	Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.	boolean	No
`description`	Helper text explaining what the user should enter.	string	No
`externalSystemAccountIdentifier`	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
`key`	Identifier the credential value is stored and referenced under.	string	Yes
`label`	Human-readable name shown for this field.	string	Yes
`placeholder`	Example value shown in the empty input to hint the expected format.	string	No
`readOnly`	Whether the field is displayed but cannot be edited by the user. Default: `false`	boolean	Yes
`required`	Whether the field must have a value. Default: `false`	boolean	Yes
`secret`	Encrypt the value at rest and mask it in the UI. Default: `false`	boolean	Yes
`tooltip`	Additional guidance shown on hover for this field.	string	No
`type`	Input control rendered for this credential field. Allowed: `text`, `password`, `text_area`	enum	Yes
[`validation`](#setupfields-text-password-text-area-validation)	Client-side validation constraint applied to the entered value.	object	No
`value`	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

Client-side validation constraint applied to the entered value.

Field	Description	Type	Required
`errorMessage`	Message shown when the value fails the pattern or format check.	string	No
`format`	Named format the entered value must match, standing in for a common regular expression. Provide this or `pattern`, not both. Allowed: `email`, `url`, `uri`, `uuid`, `date`, `datetime`	enum	No
`pattern`	Regular expression the entered value must match. Provide this or `format`, not both.	string	No

Field	Description	Type	Required
`computed`	Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.	boolean	No
`description`	Helper text explaining what the user should enter.	string	No
`externalSystemAccountIdentifier`	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
`key`	Identifier the credential value is stored and referenced under.	string	Yes
`label`	Human-readable name shown for this field.	string	Yes
[`options`](#setupfields-select-options)	Selectable choices offered for this field.	object[]	Yes
`placeholder`	Example value shown in the empty input to hint the expected format.	string	No
`readOnly`	Whether the field is displayed but cannot be edited by the user. Default: `false`	boolean	Yes
`required`	Whether the field must have a value. Default: `false`	boolean	Yes
`secret`	Encrypt the value at rest and mask it in the UI. Default: `false`	boolean	Yes
`tooltip`	Additional guidance shown on hover for this field.	string	No
`type`	Input control rendered for this credential field.	string	Yes
`value`	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

Selectable choices offered for this field.

Field	Description	Type	Required
`label`	Human-readable text shown for this option.	string	Yes
`value`	Value stored when this option is selected.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/setupFields/items" */} **Examples** ```yaml setupFields: - key: oauth_client_id label: OAuth Client ID type: text required: true - key: oauth_client_secret label: OAuth Client Secret type: password required: true secret: true ``` ## setupNotices Callouts shown while entering setup fields.

Field	Description	Type	Required
`anchor`	Field key the notice is shown above. Only valid when position is top.	string	No
`description`	Text shown in the notice.	string	Yes
`key`	Identifier for the notice.	string	Yes
`position`	Whether the notice appears above or below the fields. Allowed: `top`, `bottom` Default: `top`	enum	Yes
`type`	Visual style of the notice. Allowed: `warning`, `info` Default: `info`	enum	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/setupNotices/items" */} **Examples** ```yaml setupNotices: - key: rotation_reminder type: info description: Rotate the client secret every 90 days. position: bottom ``` ## support Help resources shown while connecting with this method.

Field	Description	Type	Required
`description`	Help text guiding the user through connecting.	string	No
[`guides`](#support-guides)	Step-by-step connection guides.	object	No
`link`	URL to external setup documentation. Defaults to the generated connector guide on docs.stackone.com when omitted.	string	No

Step-by-step connection guides.

Field	Description	Type	Required
[`config`](#support-guides-config)	Guide for the credentials end-users enter per connection.	object	No
[`setup`](#support-guides-setup)	Guide for the credentials your team registers once.	object	No

Guide for the credentials end-users enter per connection.

Field	Description	Type	Required
[`sections`](#support-guides-config-sections)	Ordered sections making up the guide.	object[]	Yes
`warning`	Cautionary note shown at the top of the guide.	string	No

Ordered sections making up the guide.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Introductory text for the section.	string	Yes
[`image`](#support-guides-config-sections-image)	Illustrative image for the section.	object	No
`list`	Ordered items elaborating the section.	string[]	No
[`steps`](#support-guides-config-sections-steps)	Ordered steps making up the section.	object[]	No
`title`	Heading for this guide section.	string	Yes

Illustrative image for the section.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

Ordered steps making up the section.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Body text describing what the user should do.	string	Yes
`displayScopes`	Whether the step shows badges for the actions its scopes unlock.	boolean	No
[`image`](#support-guides-config-sections-steps-image)	Illustrative image for the step.	object	No
`list`	Ordered items elaborating the step.	string[]	No
`title`	Heading for this guide step.	string	Yes

Illustrative image for the step.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

Guide for the credentials your team registers once.

Field	Description	Type	Required
[`sections`](#support-guides-setup-sections)	Ordered sections making up the guide.	object[]	Yes
`warning`	Cautionary note shown at the top of the guide.	string	No

Ordered sections making up the guide.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Introductory text for the section.	string	Yes
[`image`](#support-guides-setup-sections-image)	Illustrative image for the section.	object	No
`list`	Ordered items elaborating the section.	string[]	No
[`steps`](#support-guides-setup-sections-steps)	Ordered steps making up the section.	object[]	No
`title`	Heading for this guide section.	string	Yes

Illustrative image for the section.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

Ordered steps making up the section.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Body text describing what the user should do.	string	Yes
`displayScopes`	Whether the step shows badges for the actions its scopes unlock.	boolean	No
[`image`](#support-guides-setup-sections-steps-image)	Illustrative image for the step.	object	No
`list`	Ordered items elaborating the step.	string[]	No
`title`	Heading for this guide step.	string	Yes

Illustrative image for the step.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/support" */} **Examples** ```yaml support: link: https://docs.provider.com/oauth-setup description: How to register an OAuth app in the provider dashboard. guides: setup: sections: - title: Register an OAuth app content: Sign in to the provider dashboard and create an app. steps: - title: Open the Developer settings content: Click your avatar, then Developer settings. image: { src: /images/connectors/provider/dev-settings.png, alt: Developer settings menu } - title: Create a new OAuth app content: Set the redirect URL to the value shown in the Hub. ``` ## testActions Actions run to validate a connection after authentication.

Field	Description	Type	Required
[`action`](#testactions-action)	Action id or definition executed to test the connection.	union	Yes
`condition`	JEXL expression gating whether the test action runs.	string	No
`required`	Currently not in use. Default: `true`	boolean	Yes

Action id or definition executed to test the connection. A `string` value. Same fields as [actions](/connector-yaml-reference/yaml-schema/actions). {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/authentication/items/additionalProperties/anyOf/0/properties/testActions/items" */} **Examples** ```yaml testActions: - action: get_current_user required: true - action: list_admin_settings condition: '${credentials.scope.contains("admin")}' required: false ``` ## Related Declare available scopes; profiles can pin requiredScopes. Typically interpolates a ${credentials.subdomain} here. Connector-level external doc links, separate from per-auth guides. Actions referenced by testActions and refresh_token must exist in actions[]. # Actions Source: https://docs.stackone.com/connector-yaml-reference/yaml-schema/actions Field reference for the operations a connector exposes: inputs, steps, fieldConfigs, result, responses, cursor, dataSync, executionMode, compositeIdentifiers, validationRules, and examples. ## overview

Field	Description	Type	Required
`actionId`	Identifier for the action, prefixed with the connector key to form its MCP tool name.	string	Yes
`actionType`	Operation kind the engine treats this action as. Allowed: `list`, `get`, `create`, `update`, `delete`, `custom`, `refresh_token`, `event`, `unknown`	enum	Yes
[`annotations`](#annotations)	Explicit MCP tool-annotation overrides. Any field set here wins over the hint derived from `effects`.	object	No
[`authRequirements`](#authrequirements)	Per-authentication-method scopes required to run the action. Supersedes the deprecated `requiredScopes`.	object	No
`categories`	Business-domain classifications used for filtering the action.	string[]	Yes
[`compositeIdentifiers`](#compositeidentifiers)	Configuration for building a record id from multiple provider fields.	object	No
[`cursor`](#cursor)	Engine-managed cursor pagination configuration.	object	No
[`dataSync`](#datasync)	Data Sync configuration for bulk syncing this action's records.	object	No
`description`	Short description shown in the UI and MCP tool declarations.	string	Yes
`details`	Extended context about the action for agents and developers. Used as the MCP tool description in place of `description` when set.	string	No
[`effects`](#effects)	Semantic effects the action performs, used for MCP annotations and dashboard filtering.	string[]	No
`entrypointHttpMethod`	HTTP method of the primary request.	string	No
`entrypointUrl`	URL path of the action's primary request. Paired with `entrypointHttpMethod` to form the action key such as `GET /employees`, and used as the request log URL.	string	No
[`examples`](#examples)	Example input values for the action, each optionally labeled with `exampleDescription`.	object[]	No
`executionMode`	Whether the action runs synchronously or is dispatched to an async workflow. An action with a `browser_use` step must be `async`. Allowed: `sync`, `async`	enum	No
[`fieldConfigs`](#fieldconfigs)	Field-level mapping and typing configuration for the result.	array	No
[`inputs`](#inputs)	Parameters the action accepts, forming its tool input schema.	object[]	No
`label`	Human-readable display name for the action.	string	Yes
`prerequisiteActions`	Action ids this action declares as dependencies.	string[]	No
`providerEvents`	Provider event names this action handles.	string[]	No
`releaseStage`	Maturity level of the action. Allowed: `preview`, `beta`, `ga`, `deprecated`, `internal`	enum	No
`requiredScopes`	Permission scopes required to run the action. Deprecated; use `authRequirements`.	string	No
`resources`	URL to provider documentation for this action.	string	No
[`responses`](#responses)	Documented HTTP responses the action can return.	object[]	No
[`result`](#result)	Data returned to the caller, given as an expression or a map of output keys to expressions.	union	No
`schema`	Name of the output schema the action conforms to.	string	No
`schemaType`	Whether the output follows the native provider shape or the unified StackOne schema. Allowed: `native`, `unified` Default: `native`	enum	Yes
[`steps`](#steps)	Ordered steps executed to carry out the action. A single step runs one step function, and an iterator step runs step functions over each item of an array.	array	Yes
`tags`	Free-form tags for grouping and filtering the action.	string[]	No
`userScoped`	The action answers for the acting user, filtering the provider by `$.user`. The engine refuses the call when there is no acting user email. The object form also checks each returned record against the caller.	union	No
[`validationRules`](#validationrules)	Cross-field validation rules applied to the action inputs.	array	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaOverview path="/properties/actions/items" */} `actionType` tells the engine how to treat the operation. **Unified types (`list`, `get`, `create`, `update`, `delete`)** return normalized data: - Consistent response schemas across providers. - Cross-provider compatibility. - Automatic pagination handling. - Normalized error responses. A `list` action always returns `{ data: [...], next: }`. **Custom** (`custom`) returns the raw provider response, with no schema normalization. Use it for provider-specific endpoints that need full flexibility. **Special-purpose types** are used in other blocks, not `actions[]`: - `event` — an event handler under [`events.actions`](/connector-yaml-reference/yaml-schema/events#actions) that runs when a matching provider event arrives (matched via `providerEvents`). Same shape as a regular action. - `refresh_token` — the credential-refresh action under [`refreshAuthentication`](/connector-yaml-reference/yaml-schema/authentication#refreshauthentication). **Examples** ```yaml actions: - actionId: list_tickets actionType: custom effects: [read] label: List tickets description: List tickets from the provider. inputs: - name: limit description: Maximum number of results to return. type: number in: query required: false - name: offset description: Number of results to skip. type: number in: query required: false steps: - stepId: list_tickets_request description: Fetch tickets from the provider. stepFunction: functionName: request parameters: url: /tickets method: get args: - name: limit value: $.inputs.limit in: query condition: '{{present(inputs.limit)}}' - name: offset value: $.inputs.offset in: query condition: '{{present(inputs.offset)}}' result: data: $.steps.list_tickets_request.output.data ``` ## annotations Explicit MCP tool-annotation overrides. Any field set here wins over the hint derived from `effects`.

Field	Description	Type	Required
`destructiveHint`	Whether the action may delete or overwrite data.	boolean	No
`idempotentHint`	Whether repeating the action has no additional effect.	boolean	No
`openWorldHint`	Whether the action interacts with an open, external world.	boolean	No
`readOnlyHint`	Whether the action only reads data.	boolean	No
`title`	Human-readable title exposed to MCP clients.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/annotations" */} **Examples** ```yaml annotations: title: List employees readOnlyHint: true destructiveHint: false idempotentHint: true openWorldHint: false ``` ## authRequirements Per-authentication-method scopes required to run the action. Supersedes the deprecated `requiredScopes`. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/authRequirements" */} **Examples** ```yaml authRequirements: oauth2: - employees:read api_key: - employees:read ``` ## compositeIdentifiers Configuration for building a record id from multiple provider fields.

Field	Description	Type	Required
`enabled`	Whether composite identifiers are built for records.	boolean	Yes
[`fields`](#compositeidentifiers-fields)	Field mappings that make up each composite identifier.	object[]	No
`version`	Version of the composite identifier encoding.	number	No

Field mappings that make up each composite identifier.

Field	Description	Type	Required
`components`	Ordered output field keys whose values combine into the identifier.	string[]	Yes
`remote`	Provider field the identifier component is read from.	string	No
`targetFieldKey`	Key the composite identifier is written to.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/compositeIdentifiers" */} **Examples** ```yaml compositeIdentifiers: enabled: true version: 1 fields: - targetFieldKey: id remote: '$.record.identifier' components: [tenant_id, employee_id] ``` ## cursor Engine-managed cursor pagination configuration.

Field	Description	Type	Required
`enabled`	Whether cursor pagination is enabled. Only applies to list actions and has no effect on others.	boolean	Yes
`pageSize`	Number of records requested per page.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/cursor" */} **Examples** ```yaml cursor: enabled: true pageSize: 100 ``` ## dataSync Synced records are stored for reading with [Deep Query](/optimize/deep-query). See [Data Sync](/optimize/data-sync/overview). Data Sync configuration for bulk syncing this action's records.

Field	Description	Type	Required
`allowed`	Whether Data Sync is enabled for this action.	boolean	Yes
`dataKey`	Path within the step output to the records array, used when the action returns them in a single call rather than paginating.	string	No
[`incremental`](#datasync-incremental)	Change-tracking configuration for incremental syncs.	union	No
`indexField`	Field or fields forming each record's primary key during sync. Must uniquely identify each record; a value shared across records collapses them and a record missing it is dropped.	union	Yes
`maxDurationMinutes`	Maximum time a single sync run may take.	integer	No
`maxPages`	Maximum number of pages fetched in a single sync run.	integer	No
[`pagination`](#datasync-pagination)	Pagination strategy used while syncing.	union	No

Change-tracking configuration for incremental syncs.

Field	Description	Type	Required
`format`	Encoding of the timestamp value: `iso8601`, `unix_seconds`, or `unix_millis`. Allowed: `iso8601`, `unix_seconds`, `unix_millis`	enum	Yes
[`iterator`](#datasync-incremental-time-filter-iterator)	Names the request parameter carrying the last-sync timestamp and where on the request to place it.	object	Yes
[`response`](#datasync-incremental-time-filter-response)	Configures reading the newest record timestamp from each page to advance the watermark.	object	No
`safetyBufferSeconds`	Seconds subtracted from the run start time when falling back to the local clock so records near the boundary are not skipped. Default: `60`	integer	Yes
`type`	Selects the updated-since strategy where each sync requests only records changed after the last watermark.	string	Yes

Names the request parameter carrying the last-sync timestamp and where on the request to place it.

Field	Description	Type	Required
`in`	Where to add the timestamp parameter: `query`, `body`, or `headers`. Allowed: `query`, `body`, `headers`	enum	Yes
`key`	Request parameter name the last-sync timestamp is sent under.	string	Yes

Configures reading the newest record timestamp from each page to advance the watermark.

Field	Description	Type	Required
`updatedAtPath`	Path within each returned record to its last-updated timestamp, read to advance the watermark.	string	Yes

Field	Description	Type	Required
[`iterator`](#datasync-incremental-delta-token-iterator)	Names the request parameter carrying the previous delta token and where on the request to place it.	object	Yes
[`response`](#datasync-incremental-delta-token-response)	Configures reading the next delta token from the response.	object	Yes
`type`	Selects the delta-token strategy where each sync sends the token returned by the previous sync.	string	Yes

Names the request parameter carrying the previous delta token and where on the request to place it.

Field	Description	Type	Required
`in`	Where to add the delta token: `query`, `body`, or `headers`. Allowed: `query`, `body`, `headers`	enum	Yes
`key`	Request parameter name the delta token is sent under.	string	Yes

Configures reading the next delta token from the response.

Field	Description	Type	Required
`onlyOnFinalPage`	When `true`, read the delta token only from the final page of results.	boolean	No
`path`	Response key for the delta token used on the next sync: a dot-path into the action result, or a `{{ }}` expression evaluated against the result with response headers at `$.headers` (lowercased).	string	Yes

Pagination strategy used while syncing.

Field	Description	Type	Required
[`iterator`](#datasync-pagination-cursor-iterator)	Request parameter that carries the next-page cursor.	object	Yes
[`response`](#datasync-pagination-cursor-response)	How records and the next-page cursor are located in the response.	object	Yes
`stopCondition`	JEXL expression evaluated against each response to stop paging, with response headers at `$.headers` (lowercased). Defaults to stopping when the resolved next-page cursor is `null`.	string	No
`type`	Selects the cursor-based pagination strategy.	string	Yes

Request parameter that carries the next-page cursor.

Field	Description	Type	Required
`in`	Where to add the pagination parameters: `query`, `body`, or `headers`. Allowed: `query`, `body`, `headers`	enum	Yes
`key`	Request parameter the next-page cursor is sent in.	string	Yes

How records and the next-page cursor are located in the response.

Field	Description	Type	Required
`dataKey`	Response key holding the array of records for each page.	string	Yes
`nextKey`	Response key for the next-page cursor: a dot-path into the action result, or a `{{ }}` expression evaluated against the result with response headers at `$.headers` (lowercased).	string	Yes

Field	Description	Type	Required
[`iterator`](#datasync-pagination-offset-iterator)	Request parameters that page through results by offset and limit.	object	Yes
[`response`](#datasync-pagination-offset-response)	How each page of records is located in the response.	object	Yes
`stopCondition`	JEXL expression evaluated against each response to stop paging, with response headers at `$.headers` (lowercased). Defaults to stopping when the data key returns no records.	string	No
`type`	Selects the offset-based pagination strategy.	string	Yes

Request parameters that page through results by offset and limit.

Field	Description	Type	Required
`defaultLimit`	Number of records requested per page. Defaults to `100` when omitted.	number	No
`in`	Where to add the pagination parameters: `query`, `body`, or `headers`. Allowed: `query`, `body`, `headers`	enum	Yes
`limitKey`	Request parameter set to the number of records requested per page.	string	Yes
`offsetKey`	Request parameter set to the offset of the first record on each page.	string	Yes
`startOffset`	Offset sent on the first page. Defaults to `0`. Set to `1` for APIs that count records from 1 rather than 0, such as SCIM's `startIndex`.	integer	No

How each page of records is located in the response.

Field	Description	Type	Required
`dataKey`	Response key holding the array of records for each page.	string	Yes

Field	Description	Type	Required
[`iterator`](#datasync-pagination-page-iterator)	Request parameters that page through results by page number.	object	Yes
[`response`](#datasync-pagination-page-response)	How each page of records is located in the response.	object	Yes
`stopCondition`	JEXL expression evaluated against each response to stop paging, with response headers at `$.headers` (lowercased). Defaults to stopping when the data key returns no records.	string	No
`type`	Selects the page-number pagination strategy.	string	Yes

Request parameters that page through results by page number.

Field	Description	Type	Required
`defaultPageSize`	Number of records requested per page. Defaults to `100` when omitted.	number	No
`in`	Where to add the pagination parameters: `query`, `body`, or `headers`. Allowed: `query`, `body`, `headers`	enum	Yes
`pageKey`	Request parameter set to the page number for each request.	string	Yes
`pageSizeKey`	Request parameter set to the number of records requested per page. Omit when the endpoint takes no page-size parameter.	string	No
`startPage`	Page number requested for the first page. Defaults to `1` when omitted.	number	No

How each page of records is located in the response.

Field	Description	Type	Required
`dataKey`	Response key holding the array of records for each page.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/dataSync" */} **Examples** ```yaml dataSync: allowed: true indexField: id pagination: type: cursor response: dataKey: data nextKey: next iterator: key: next in: query incremental: { ... } ``` ```yaml dataSync: allowed: true indexField: id pagination: type: offset response: dataKey: data.data iterator: offsetKey: offset limitKey: limit in: query incremental: { ... } ``` ```yaml dataSync: allowed: true indexField: id pagination: type: page response: dataKey: data.records iterator: pageKey: page pageSizeKey: per_page startPage: 1 in: query incremental: { ... } ``` ```yaml dataSync: allowed: true indexField: id pagination: { ... } incremental: type: time_filter iterator: key: updated_since in: query format: iso8601 ``` ```yaml dataSync: allowed: true indexField: id pagination: { ... } incremental: type: delta_token iterator: key: after in: query response: path: data.cursor ``` ## effects Semantic effects the action performs, used for MCP annotations and dashboard filtering. Optional, but worth setting on every action so an MCP client can auto-approve reads and prompt before writes. | Effect | Use for | |--------|---------| | `read` | Fetching a record or a list. Changes nothing. | | `search` | Querying with filters. Changes nothing. | | `write` | Creating or updating records. | | `delete` | Removing records. | | `execute` | Operations that aren't CRUD: send, sync, deploy, approve, merge. | An action can carry more than one effect. A find-or-create gets `[read, write]`. | Annotation | Derived from | |------------|--------------| | `readOnlyHint` | `true` when every effect is `read` or `search`. | | `destructiveHint` | `true` when effects include `delete`. | | `openWorldHint` | Always `true`, since actions call external provider APIs. | | `title` | The action's `label`. | | `idempotentHint` | Never derived. Set it with `annotations`. | With no `effects` and no `annotations` override, no hints are emitted, so a read looks no safer than a delete. Annotations are hints, not enforcement. Clients use them for grouping and approval defaults, not as a security boundary. To actually restrict what a linked account can call, disable the actions on its Connector Profile. See [Scoping connectors](/secure/scoping-connectors). **Examples** ```yaml effects: - read ``` ## examples Example input values for the action, each optionally labeled with `exampleDescription`.

Field	Description	Type	Required
`exampleDescription`	Explains what this usage example demonstrates.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/examples/items" */} **Examples** ```yaml examples: - exampleDescription: Fetch a single active employee. input: employee_id: emp_123 output: id: emp_123 name: Ada Lovelace status: active - exampleDescription: Employee not found. input: employee_id: emp_does_not_exist output: error: not_found statusCode: 404 ``` ## fieldConfigs Field-level mapping and typing configuration for the result. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/fieldConfigs/items" */} **Examples** ```yaml fieldConfigs: - targetFieldKey: id alias: employee_id type: string - targetFieldKey: name expression: '${item.first_name} ${item.last_name}' type: string - targetFieldKey: country alias: country_code type: string enumMapper: matcher: country_alpha2code_by_country_name - targetFieldKey: address type: object properties: - { targetFieldKey: street, alias: street_address, type: string } - { targetFieldKey: city, alias: city, type: string } - targetFieldKey: salary type: number requiredScopes: read:compensation # hidden if scope not granted ``` ## inputs Parameters the action accepts, forming its tool input schema.

Field	Description	Type	Required
`array`	Whether the input accepts a list of values. Default: `false`	boolean	Yes
`arrayFormat`	How a list input's values are formatted in the request, such as repeated, comma-separated, or bracketed. Currently not in use. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`description`	Explains the input for callers and generated tool schemas.	string	Yes
`in`	Part of the HTTP request this input is placed in. Allowed: `body`, `query`, `path`, `headers`	enum	Yes
`name`	Parameter name exposed to callers and mapped into the request.	string	Yes
[`oneOf`](#inputs-oneof)	Allowed values when the input is an enum.	union	No
`properties`	Nested inputs when the input is an object. Each has the same shape as a top-level input, minus `in`.	object[]	No
`required`	Whether the caller must supply this input.	boolean	Yes
[`rules`](#inputs-rules)	Validation rules applied to the input value.	object	No
`type`	Data type of the input value. Allowed: `string`, `number`, `boolean`, `datetime_string`, `object`, `enum`	enum	No
`variants`	An input that accepts more than one type. Provide at least two variants, each defining one of those types the way an input does. The input itself sets no top-level `type`, `array`, `properties`, `oneOf`, or `rules`.	object[]	No

Allowed values when the input is an enum.

Field	Description	Type	Required
`values`	Explicit list of allowed enum values.	string[]	Yes

Field	Description	Type	Required
`ref`	Name of a shared enum definition supplying the allowed values. One of: `employment_status`, `employment_type`, `gender`, `marital_status`.	string	Yes

Validation rules applied to the input value.

Field	Description	Type	Required
`errorMessage`	Message shown when the value violates a rule.	string	No
`format`	Named format the value must conform to. Allowed: `email`, `url`, `uri`, `uuid`, `date`, `datetime`	enum	No
`max`	Maximum numeric value allowed.	number	No
`maxLength`	Maximum number of characters the value may have.	number	No
`min`	Minimum numeric value allowed.	number	No
`minLength`	Minimum number of characters the value must have.	number	No
`pattern`	Regular expression the value must match.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/inputs/items" */} **Examples** ```yaml inputs: - name: employee_id type: string required: true in: path description: Provider's employee identifier. - name: status type: enum required: false in: query description: Filter by employment status. oneOf: values: [active, inactive, terminated] - name: hire_date type: datetime_string required: false in: body description: ISO 8601 hire date. rules: format: date - name: skills type: string array: true arrayFormat: comma in: query description: Comma-separated skill filter. - name: destination in: body required: true description: Where to send the payload. The type field selects the variant. variants: - type: object description: Post to a webhook URL. properties: - name: type type: enum required: true oneOf: values: [webhook] - name: url type: string required: true - type: object description: Send to an email address. properties: - name: type type: enum required: true oneOf: values: [email] - name: address type: string required: true ``` ## responses Documented HTTP responses the action can return.

Field	Description	Type	Required
`description`	What this response status means.	string	Yes
`statusCode`	HTTP status code being documented.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/responses/items" */} **Examples** ```yaml responses: - statusCode: 200 description: Employee record returned. - statusCode: 404 description: No employee found with the provided ID. - statusCode: 409 description: Conflicts with an existing record; check inputs. ``` ## result Data returned to the caller, given as an expression or a map of output keys to expressions. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/result" */} **Examples** ```yaml result: '${steps.cast.output.data}' ``` ```yaml result: user: '${steps.fetch_user.output.data}' team: '${steps.fetch_team.output.data}' last_synced_at: '{{now()}}' ``` ## steps See [Step Functions](/connector-yaml-reference/step-functions/overview) for the full catalog and their parameters. Ordered steps executed to carry out the action. A single step runs one step function, and an iterator step runs step functions over each item of an array.

Field	Description	Type	Required
`condition`	JEXL expression gating whether this step runs.	string	No
`description`	Explains what this step does.	string	Yes
`ignoreError`	Whether a failure in this step is ignored so execution continues.	boolean	No
`onConditionError`	How to behave when the condition expression errors: `false` (default) skips the step, `true` runs it anyway, and `break` halts the action. Allowed: `true`, `false`, `break`	enum	No
[`stepFunction`](#steps-single-step-stepfunction)	Step function executed by this step.	object	Yes
`stepId`	Identifier for this step, used to reference its output.	string	Yes

Step function executed by this step.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

Field	Description	Type	Required
`condition`	JEXL expression gating whether this step runs.	string	No
`description`	Explains what this step does.	string	Yes
`ignoreError`	Whether a failure in this step is ignored so execution continues.	boolean	No
`iterator`	Expression that produces the array this step loops over. The step function(s) run once per item until the array is exhausted, halting early if an item fails and `ignoreError` is not set.	string	Yes
`onConditionError`	How to behave when the condition expression errors: `false` (default) skips the step, `true` runs it anyway, and `break` halts the action. Allowed: `true`, `false`, `break`	enum	No
[`stepFunction`](#steps-iterator-step-stepfunction)	Step function run for each iterated item. Provide this or `stepFunctions`, not both.	object	No
[`stepFunctions`](#steps-iterator-step-stepfunctions)	Step functions run in sequence for each iterated item. Provide this or `stepFunction`, not both.	object[]	No
`stepId`	Identifier for this step, used to reference its output.	string	Yes

Step function run for each iterated item. Provide this or `stepFunctions`, not both.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

Step functions run in sequence for each iterated item. Provide this or `stepFunction`, not both.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

Field	Description	Type	Required
`errorMessage`	Message shown when the rule is violated.	string	No
`fields`	Input names of which at least one must be provided.	string[]	Yes
`rule`	Requires at least one of the listed inputs to be provided.	string	Yes

Field	Description	Type	Required
[`condition`](#validationrules-requiredif-condition)	Condition under which the field is required.	object	Yes
`errorMessage`	Message shown when the rule is violated.	string	No
`field`	Input that becomes required when the condition holds.	string	Yes
`rule`	Requires an input when another field satisfies a condition.	string	Yes

Condition under which the field is required.

Field	Description	Type	Required
`equals`	Condition holds when the referenced field equals this value.	string	No
`field`	Name of the other input this condition inspects.	string	Yes
`notEquals`	Condition holds when the referenced field does not equal this value.	string	No
`present`	When true, the condition holds if the referenced field is present. When false, it holds if the field is absent.	boolean	No

Field	Description	Type	Required
`errorMessage`	Message shown when the rule is violated.	string	No
`fields`	Input names of which at most one may be provided.	string[]	Yes
`rule`	Allows at most one of the listed inputs to be provided.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/validationRules/items" */} **Examples** ```yaml validationRules: - rule: atLeastOneOf fields: [email, employee_id] errorMessage: Provide either email or employee_id. ``` ```yaml validationRules: - rule: requiredIf field: termination_date condition: { field: status, equals: terminated } errorMessage: termination_date is required when status is "terminated". ``` ```yaml validationRules: - rule: mutuallyExclusive fields: [start_date, anchor_date] errorMessage: Use one of start_date or anchor_date, not both. ``` ## Related Full catalog of stepFunction implementations. JEXL syntax for condition, iterator, result, and step inputs. # Events Source: https://docs.stackone.com/connector-yaml-reference/yaml-schema/events Field reference for a connector's events block: event actions, router, setup lifecycle, and the external account id extractor. Configures a connector's inbound webhooks. For how event handling works end to end, see [Implementing events](/connector-building/implementing-events). ## overview Event and webhook configuration for the connector.

Field	Description	Type	Required
[`actions`](#actions)	Event actions that process incoming provider events.	object[]	No
[`externalAccountIdExtractor`](#externalaccountidextractor)	Action that reads the provider's external account identifier from an incoming payload so the event can be matched to a linked account. It is a `custom` action with a required `result`.	object	No
[`guides`](#guides)	Manual webhook setup guides.	object	No
[`router`](#router)	Rules mapping incoming payloads to event actions.	object	No
[`setup`](#setup)	Programmatic webhook lifecycle configuration.	object	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaOverview path="/properties/events" */} **Examples** ```yaml events: setup: creation: steps: - stepId: create_webhook description: Register a webhook receiver. stepFunction: functionName: request version: v1 parameters: url: /webhooks method: post args: - name: url value: '${inputs.callbackUrl}' in: body result: '$.id' deletion: steps: - stepId: delete_webhook description: Remove the webhook receiver. stepFunction: functionName: request version: v1 parameters: url: '/webhooks/${inputs.remoteId}' method: delete router: rules: - when: '${event.type == "user.created"}' then: { action: user_created_event } ``` ## actions Event actions that process incoming provider events. Same fields as [actions](/connector-yaml-reference/yaml-schema/actions), plus:

Field	Description	Type	Required
`requiresManualSetup`	Whether the webhook must be configured manually in the provider UI. Pair with `guides.setup` to document that setup.	boolean	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/events/properties/actions/items" */} **Examples** ```yaml events: actions: - actionId: handle_ticket_created actionType: event label: Ticket created webhook description: Processes ticket.created events from the provider. providerEvents: [ticket.created] inputs: - name: event description: The provider event object from the delivery. type: object in: body required: false steps: - stepId: emit description: Emit the ticket.created event to StackOne's dispatcher. stepFunction: functionName: emit_event parameters: event: eventType: ticket.created eventId: $.inputs.event.id data: $.inputs.event result: statusCode: 200 body: status: OK ``` ## externalAccountIdExtractor Action that reads the provider's external account identifier from an incoming payload so the event can be matched to a linked account. It is a `custom` action with a required `result`. Same fields as [actions](/connector-yaml-reference/yaml-schema/actions). {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/events/properties/externalAccountIdExtractor" */} **Examples** ```yaml events: externalAccountIdExtractor: actionId: extract_account_id actionType: custom label: Extract account ID from event description: Map provider tenant ID to StackOne linked account. steps: - stepId: lookup stepFunction: functionName: request version: v1 parameters: url: 'https://internal/accounts/by-tenant/${inputs.tenant_id}' method: get result: '${steps.lookup.output.data.linked_account_id}' ``` ## guides Manual webhook setup guides.

Field	Description	Type	Required
[`setup`](#guides-setup)	Guide for configuring webhooks in the provider UI.	object	No

Guide for configuring webhooks in the provider UI.

Field	Description	Type	Required
[`sections`](#guides-setup-sections)	Ordered sections making up the guide.	object[]	Yes
`warning`	Cautionary note shown at the top of the guide.	string	No

Ordered sections making up the guide.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Introductory text for the section.	string	Yes
[`image`](#guides-setup-sections-image)	Illustrative image for the section.	object	No
`list`	Ordered items elaborating the section.	string[]	No
[`steps`](#guides-setup-sections-steps)	Ordered steps making up the section.	object[]	No
`title`	Heading for this guide section.	string	Yes

Illustrative image for the section.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

Ordered steps making up the section.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Body text describing what the user should do.	string	Yes
`displayScopes`	Whether the step shows badges for the actions its scopes unlock.	boolean	No
[`image`](#guides-setup-sections-steps-image)	Illustrative image for the step.	object	No
`list`	Ordered items elaborating the step.	string[]	No
`title`	Heading for this guide step.	string	Yes

Illustrative image for the step.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/events/properties/guides" */} **Examples** ```yaml guides: setup: sections: - title: Enable webhooks content: Turn on event delivery in the provider dashboard. steps: - title: Open webhook settings content: Go to Settings, then Webhooks. ``` ## router Rules mapping incoming payloads to event actions.

Field	Description	Type	Required
[`delivery`](#router-delivery)	Rules matched against the whole delivery payload, rather than the individual events `itemsPath` splits it into. The first match short-circuits, so the per-event `rules` are skipped.	object[]	No
`itemsPath`	JEXL expression that splits a batched delivery payload into individual events, so each is routed on its own through `rules`. When omitted, the whole payload is treated as a single event.	string	No
[`rules`](#router-rules)	Rules matched in order against each individual event, where the first match maps it to an event action. Skipped when a `delivery` rule matches.	object[]	Yes

Rules matched against the whole delivery payload, rather than the individual events `itemsPath` splits it into. The first match short-circuits, so the per-event `rules` are skipped.

Field	Description	Type	Required
[`then`](#router-delivery-then)	Action to invoke when the rule matches.	object	Yes
`when`	JEXL expression evaluated against the incoming request. This rule is selected when the expression returns anything other than null, false, or undefined.	string	Yes

Action to invoke when the rule matches.

Field	Description	Type	Required
`action`	Event action id invoked when the rule matches.	string	Yes
`input`	JEXL expressions evaluated against the incoming request whose results become the invoked action's input.	object	No

Rules matched in order against each individual event, where the first match maps it to an event action. Skipped when a `delivery` rule matches.

Field	Description	Type	Required
[`then`](#router-rules-then)	Action to invoke when the rule matches.	object	Yes
`when`	JEXL expression evaluated against the incoming request. This rule is selected when the expression returns anything other than null, false, or undefined.	string	Yes

Action to invoke when the rule matches.

Field	Description	Type	Required
`action`	Event action id invoked when the rule matches.	string	Yes
`input`	JEXL expressions evaluated against the incoming request whose results become the invoked action's input.	object	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/events/properties/router" */} **Examples** ```yaml events: router: rules: - when: '${event.type == "user.created"}' then: { action: handle_user_created } - when: '${event.type == "user.updated" && event.changes.contains("email")}' then: action: handle_email_change input: user_id: '${event.data.id}' new_email: '${event.data.email}' ``` ## setup Programmatic webhook lifecycle configuration.

Field	Description	Type	Required
[`activation`](#setup-activation)	Optional phase that activates the receiver after creation. Must reference `${inputs.remoteId}` in at least one step parameter.	object	No
[`creation`](#setup-creation)	Phase that registers the webhook receiver.	object	Yes
[`deletion`](#setup-deletion)	Phase that removes the webhook receiver. Must reference `${inputs.remoteId}` in at least one step parameter.	object	Yes
`isConsolidated`	Whether one receiver handles all events rather than one per event. Default: `false`	boolean	Yes

Optional phase that activates the receiver after creation. Must reference `${inputs.remoteId}` in at least one step parameter.

Field	Description	Type	Required
`result`	Value produced by the phase, such as the created webhook id.	string	No
`steps`	Ordered steps performed in this webhook phase.	array	Yes

Phase that registers the webhook receiver.

Field	Description	Type	Required
`result`	Expression selecting the value this phase produces, such as the created receiver's remote id (e.g. `$.steps.create.output.data.id`), which later phases reference as `${inputs.remoteId}`.	string	Yes
`steps`	Ordered steps performed in this webhook phase.	array	Yes

Phase that removes the webhook receiver. Must reference `${inputs.remoteId}` in at least one step parameter.

Field	Description	Type	Required
`result`	Value produced by the phase, such as the created webhook id.	string	No
`steps`	Ordered steps performed in this webhook phase.	array	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/events/properties/setup" */} **Examples** ```yaml events: setup: creation: steps: - stepId: create_webhook description: Register a webhook receiver. stepFunction: functionName: request version: v1 parameters: url: /webhooks method: post args: - { name: url, value: '${inputs.callbackUrl}', in: body } - { name: events, value: '${inputs.eventTypes}', in: body } result: '$.id' activation: steps: - stepId: activate description: Mark webhook active. stepFunction: functionName: request version: v1 parameters: url: '/webhooks/${inputs.remoteId}/activate' method: post deletion: steps: - stepId: delete_webhook description: Remove the receiver. stepFunction: functionName: request version: v1 parameters: url: '/webhooks/${inputs.remoteId}' method: delete isConsolidated: false ``` ## Related The full action shape event actions and the extractor are built from. Fan out events to downstream subscribers. JEXL syntax for the router's when rules. The step shape each setup phase reuses. # Step Functions Source: https://docs.stackone.com/connector-yaml-reference/step-functions/overview The operations you chain together as steps to build a connector's actions and event setup. **Step functions** are the operations a connector runs, one step at a time, to carry out an [action](/connector-yaml-reference/yaml-schema/actions) or set up [events](/connector-yaml-reference/yaml-schema/events). Each step takes parameters and returns output that later steps and the result of the action or event setup can use. See [Expression Language](/connector-yaml-reference/expression-language) for how to reference a step's output. ## Step shape Steps take one of two shapes: Runs one step function once.

Field	Description	Type	Required
`condition`	JEXL expression gating whether this step runs.	string	No
`description`	Explains what this step does.	string	Yes
`ignoreError`	Whether a failure in this step is ignored so execution continues.	boolean	No
`onConditionError`	How to behave when the condition expression errors: `false` (default) skips the step, `true` runs it anyway, and `break` halts the action. Allowed: `true`, `false`, `break`	enum	No
[`stepFunction`](#steps-stepfunction)	Step function executed by this step.	object	Yes
`stepId`	Identifier for this step, used to reference its output.	string	Yes

Step function executed by this step.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

Field	Description	Type	Required
`condition`	JEXL expression gating whether this step runs.	string	No
`description`	Explains what this step does.	string	Yes
`ignoreError`	Whether a failure in this step is ignored so execution continues.	boolean	No
`iterator`	Expression that produces the array this step loops over. The step function(s) run once per item until the array is exhausted, halting early if an item fails and `ignoreError` is not set.	string	Yes
`onConditionError`	How to behave when the condition expression errors: `false` (default) skips the step, `true` runs it anyway, and `break` halts the action. Allowed: `true`, `false`, `break`	enum	No
[`stepFunction`](#steps-stepfunction)	Step function run for each iterated item. Provide this or `stepFunctions`, not both.	object	No
[`stepFunctions`](#steps-stepfunctions)	Step functions run in sequence for each iterated item. Provide this or `stepFunction`, not both.	object[]	No
`stepId`	Identifier for this step, used to reference its output.	string	Yes

Step function run for each iterated item. Provide this or `stepFunctions`, not both.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

Step functions run in sequence for each iterated item. Provide this or `stepFunction`, not both.

Field	Description	Type	Required
`functionName`	Name of the step function to execute.	string	Yes
`parameters`	Arguments passed to the step function.	object	Yes
`version`	Version of the step function to use.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: SchemaFields path="/properties/actions/items/properties/steps/items/anyOf/1" */} ## Step functions ### Requests Calls that send a request and return a response for later steps to use. Sends an HTTP request to the provider's API and returns the response. Sends HTTP requests to a paginated endpoint until it has one page of results, then returns a cursor for the next page. Sends a SOAP request to the provider and returns the parsed response. Sends SOAP requests to a paginated endpoint until it has one page of results, then returns a cursor for the next page. Calls a tool on the provider's MCP server, or lists the tools it offers. Invokes an AWS Lambda function, returning its response when invoked synchronously. Runs another action and returns its result. ### Authentication Prepare credentials that later requests use for authorization. Signs a JWT with a private key, for later requests to use as a credential. ### Transform Data Work on manipulating data already available in the action from the current context and previous steps. Maps fields from source data onto the shape the action returns. Converts fields in source data to their declared types. Combines the output of several earlier steps into one record or list. Returns fixed values, or the result of an expression. ### Files Upload files to a provider or download them from one. Uploads a file to the provider as a multipart form. Uploads raw binary content to the provider. Downloads a file from the provider, as a buffer or a stream. ### Events & Automation Start work outside the action's request and response flow. Emits an event with a type, date and payload. Runs a task in a browser session, starting at a given URL. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionCards */} # browser_use Source: https://docs.stackone.com/connector-yaml-reference/step-functions/browser-use Step function: browser_use Browser use is only available on certain plans. Each run also consumes credits from your allowance. See [plans and pricing](https://www.stackone.com/pricing/). Runs a task in a browser session, starting at a given URL. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="browser_use" */} Any action whose `steps[]` includes `browser_use` **must** declare `executionMode: async` on the action. The runtime enforces this — a sync action containing `browser_use` fails schema validation at build time. ## Input

Field	Description	Type	Required
[`auth`](#auth)	Credential handling for the browser task.	object	No
[`budgets`](#budgets)	Execution limits the task must run within.	object	Yes
`locale`	Locale the browser session runs in.	string	No
`startUrl`	URL where the browser session begins. Format: `uri`	string	Yes
`systemPrompt`	Author-defined preamble, persona, and guardrails applied to every invocation.	string	No
[`viewport`](#viewport)	Browser viewport dimensions.	object	No

Credential handling for the browser task.

Field	Description	Type	Required
`allowedDomains`	Overrides the default allowed-domains policy, for auth flows that cross a domain boundary.	string[]	No
`requiresSession`	Reserved for tasks that need a pre-authenticated browser session rather than form substitution. Not yet in use.	boolean	No
`sensitiveKeys`	Credential keys masked from the LLM and substituted only at the typing layer.	string[]	No

Execution limits the task must run within.

Field	Description	Type	Required
`maxDurationMs`	Maximum task duration in milliseconds.	integer	Yes
`maxSteps`	Maximum number of steps the agent may take.	integer	Yes

Browser viewport dimensions.

Field	Description	Type	Required
`height`	Viewport height in pixels.	integer	Yes
`width`	Viewport width in pixels.	integer	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="browser_use" version="v1" kind="input" */} ## Output {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="browser_use" version="v1" kind="output" */} # call_action Source: https://docs.stackone.com/connector-yaml-reference/step-functions/call-action Step function: call_action Runs another action and returns its result. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="call_action" */} ## Input

Field	Description	Type	Required
`actionId`	Id of the action to run, with or without the connector key prefix. Must be a literal: expressions are rejected so that cycles can be caught at validation time. Pattern: `^[A-Za-z0-9_-]+$`	string	Yes
[`inputs`](#inputs)	Inputs for the callee, grouped by the location each one is declared `in:`. A value written under the wrong location is dropped rather than reported, and a callee that declares no inputs ignores all of them.	object	No

Inputs for the callee, grouped by the location each one is declared `in:`. A value written under the wrong location is dropped rather than reported, and a callee that declares no inputs ignores all of them.

Field	Description	Type	Required
`body`	Values for the callee's inputs declared `in: body`.	any	No
`headers`	Values for the callee's inputs declared `in: header`.	object	No
`path`	Values for the callee's inputs declared `in: path`.	object	No
`query`	Values for the callee's inputs declared `in: query`.	object	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="call_action" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The callee's `data`, when its result declares one. A result that is not an object is placed here whole, and a failed call puts the provider's parsed error body here.	any	No
`message`	Error message, present only when the call failed.	string	No
`raw`	The callee's raw provider response, present only when the call failed.	any	No
`statusCode`	Status code of the callee's response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="call_action" version="v1" kind="output" */} # code_execution_lambda Source: https://docs.stackone.com/connector-yaml-reference/step-functions/code-execution-lambda Step function: code_execution_lambda Invokes an AWS Lambda function, returning its response when invoked synchronously. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="code_execution_lambda" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Key/value pairs combined into the JSON payload sent to the Lambda function	object[]	No
`dataKey`	Path to the field in the Lambda response to extract as data.	string	No
`endpoint`	Custom Lambda service endpoint URL to call instead of the default.	string	No
`invocationType`	How the Lambda is invoked. `RequestResponse` waits synchronously for the Lambda response, `Event` fires asynchronously and returns no response body, and `DryRun` validates parameters and permissions without invoking the function. Allowed: `RequestResponse`, `Event`, `DryRun`	enum	No
`lambdaName`	Name or ARN of the Lambda function to invoke.	string	Yes
`qualifier`	Function version or alias to invoke.	string	No
`region`	AWS region the Lambda function runs in.	string	No

Key/value pairs combined into the JSON payload sent to the Lambda function

Field	Description	Type	Required
`condition`	A JEXL expression that includes the field only when it evaluates true.	string	No
`name`	Payload field name.	string	Yes
`value`	Payload field value. Supports expressions.	any	Yes

Field	Description	Type	Required
`data`	The parsed Lambda response payload, or the value at `dataKey` when `dataKey` is set.	any	No
`executedVersion`	Version of the Lambda function that was invoked.	string	No
`message`	Status or error message from the response.	string	No
`raw`	The full Lambda invocation result, including the parsed `payload`, `statusCode`, and `executedVersion`.	any	No
`statusCode`	HTTP status code of the Lambda invocation.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="code_execution_lambda" version="v1" kind="output" */} # download_file Source: https://docs.stackone.com/connector-yaml-reference/step-functions/download-file Step function: download_file Downloads a file from the provider. Set `responseMode: stream` for any file an action returns: REST pipes the bytes to the caller, and an MCP tool call returns a single-use download link with the file's name, type and size. A streaming step must be the last step of its action. The default, `buffer`, returns the content in `data`, which only suits content a later step in the same action needs to read. Use `fileName` when the provider's response carries no file name. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="download_file" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Additional request parameters sent as query params, headers, or the request body, per each entry's `in`.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the download.	string	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`encoding`	Encoding applied to `data` when `responseMode` is `buffer`. Ignored when streaming. Use `none` to return a raw Buffer. Allowed: `base64`, `utf8`, `binary`, `raw`, `none` Default: `base64`	enum	Yes
`fileName`	Name to give the downloaded file, overriding any name from the provider's Content-Disposition header or `response.fileNameKey`. Supports expressions, so it can come from an earlier step such as a metadata lookup. Falls back to the provider's name when it resolves to nothing. A name with no extension gets one from the download's content type, so an exported document named `Q3 plan` saves as `Q3 plan.pdf`.	string	No
`followRedirects`	Whether to follow HTTP redirects. Default: `true`	boolean	Yes
`maxRedirects`	Maximum number of redirects to follow. Default: `5`	number	Yes
`method`	HTTP method to use for the download. Allowed: `get`, `post`, `put`, `delete`, `patch` Default: `get`	enum	Yes
[`response`](#response)	Options for extracting file content from a JSON-wrapped response.	object	No
`responseMode`	How the file is returned. `buffer` (the default) holds the whole file in memory and returns it in `data`, encoded per `encoding`, so an MCP tool call carries the entire file inline. `stream` returns a readable stream instead: REST pipes the bytes to the caller and an MCP tool call returns a single-use download link. Use `stream` for files. A streaming step must be the last step of its action. Allowed: `buffer`, `stream` Default: `buffer`	enum	Yes
`responseType`	Underlying HTTP response type requested. Used only when responseMode is buffer. Allowed: `arraybuffer`, `blob`, `text`, `json` Default: `arraybuffer`	enum	Yes
`url`	Download endpoint path appended to the base URL.	string	Yes

Additional request parameters sent as query params, headers, or the request body, per each entry's `in`.

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`spread`	Merges the value's object entries into the target location instead of setting a single named field.	boolean	No
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Remaps provider error responses to different statuses or messages. Useful for GraphQL APIs that return errors with a 200 status, normalizing provider-specific error formats, and giving AI agents clearer error messages.

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

Options for extracting file content from a JSON-wrapped response.

Field	Description	Type	Required
`contentIsBase64`	Whether the content in the JSON response is already base64 encoded. Default: `false`	boolean	Yes
`contentType`	Fallback content type used when the JSON response exposes none to extract. `contentTypeKey` wins if it resolves.	string	No
`contentTypeKey`	JSONPath to the content type within a JSON-wrapped response.	string	No
`dataKey`	JSONPath to the file content within a JSON-wrapped response.	string	No
`fileNameKey`	JSONPath to the filename within a JSON-wrapped response.	string	No
`forwardAuth`	Whether to forward authentication headers to the secondary download request when following urlKey. Default: `false`	boolean	Yes
`urlKey`	JSONPath to a download URL in the response to follow for the file.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="download_file" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`contentDisposition`	Content-Disposition header value for the client to use.	string	No
`data`	Downloaded file content. A string in the format set by the `encoding` input (base64 by default), or a raw binary Buffer when `encoding: "none"`. Absent when `responseMode: "stream"` (content is piped via the stream output instead).	union	No
[`fileMetadata`](#filemetadata)	File metadata extracted from response headers or a JSON-wrapped response.	object	No
`finalUrl`	Final URL the file was downloaded from after redirects or a followed link.	string	No
`headers`	All response headers returned with the download.	object	No
`message`	Status or error message from the response.	string	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

File metadata extracted from response headers or a JSON-wrapped response.

Field	Description	Type	Required
`contentLength`	Size of the file in bytes.	number	No
`contentType`	MIME type of the downloaded file.	string	No
`etag`	Entity tag identifying the file version.	string	No
`fileName`	Name of the downloaded file.	string	No
`lastModified`	Last-modified timestamp reported for the file.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="download_file" version="v1" kind="output" */} # emit_event Source: https://docs.stackone.com/connector-yaml-reference/step-functions/emit-event Step function: emit_event Emits an event with a type, date and payload. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="emit_event" */} ## Input

Field	Description	Type	Required
[`event`](#event)	The event to emit.	object	No

The event to emit.

Field	Description	Type	Required
`data`	Normalized payload carried by the event.	any	No
`eventDate`	Timestamp for when the event occurred.	string	No
`eventId`	Unique identifier for this event.	string	No
`eventType`	Name of the event type being emitted.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="emit_event" version="v1" kind="input" */} ## Output {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="emit_event" version="v1" kind="output" */} # group_data Source: https://docs.stackone.com/connector-yaml-reference/step-functions/group-data Step function: group_data Combines the output of several earlier steps into one record or list. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="group_data" */} ## Input

Field	Description	Type	Required
`isSingleRecord`	When true, returns a single record keyed by step ID, otherwise an array merged per key across steps.	boolean	No
`stepsDataToGroup`	IDs of the steps whose output data should be grouped together.	string[]	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="group_data" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The combined output data grouped from the referenced steps.	any	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="group_data" version="v1" kind="output" */} # map_fields Source: https://docs.stackone.com/connector-yaml-reference/step-functions/map-fields Step function: map_fields Maps fields from source data onto the shape the action returns. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="map_fields" */} ## Input

Field	Description	Type	Required
`dataSource`	Reference to the source data to transform.	string	Yes
`externalSources`	Additional named data sources referenced by mapping expressions.	object	No
`fields`	Field mapping definitions applied to the source data.	array	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="map_fields" version="v2" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The mapped fields produced from the source data.	any	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="map_fields" version="v2" kind="output" */} # mcp_request Source: https://docs.stackone.com/connector-yaml-reference/step-functions/mcp-request Step function: mcp_request Calls a tool on the provider's MCP server, or lists the tools it offers. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="mcp_request" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Arguments passed to the MCP tool call.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the MCP server.	string	No
`method`	The MCP method to call. Either `tools/call` or `tools/list`. Allowed: `tools/call`, `tools/list` Default: `tools/call`	enum	Yes
`timeout`	Request timeout in milliseconds.	integer	No
`toolName`	Name of the tool to call. Required when method is tools/call.	string	No
`url`	MCP server endpoint path.	string	No

Arguments passed to the MCP tool call.

Field	Description	Type	Required
`condition`	A JEXL expression that includes the argument only when it evaluates true.	string	No
`name`	Name of the argument.	string	Yes
`value`	Value of the argument. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="mcp_request" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The parsed MCP response. For `tools/call` it holds the tool result, for `tools/list` it holds the list of tools.	any	No
`message`	Status or error message from the response.	string	No
`raw`	The raw MCP response before parsing.	any	No
`statusCode`	Returns 200 for success, or 502 when the tool returns an error.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="mcp_request" version="v1" kind="output" */} # paginated_request Source: https://docs.stackone.com/connector-yaml-reference/step-functions/paginated-request Step function: paginated_request Sends HTTP requests to a paginated endpoint until it has one page of results, then returns a cursor for the next page. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="paginated_request" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Request parameters to send as query, body, or header values.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Base URL the paginated requests are made against.	string	Yes
`cacheTTL`	Minutes to serve each page from the shared per-account response cache. 0 or omitted disables caching.	integer	No
[`cursor`](#cursor)	Pagination position carried over from the previous page request.	object	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`encodeQueryParams`	Whether to URL-encode query parameter values before sending.	boolean	No
[`iterator`](#iterator)	Controls how subsequent pages are requested.	object	Yes
`method`	HTTP method to use: get, post, put, patch, or delete. Allowed: `get`, `post`, `put`, `delete`, `patch`	enum	Yes
[`response`](#response)	Controls how each page response is parsed and paginated.	object	No
[`saml`](#saml)	Generates a signed SAML assertion and merges it into the request body for token exchange.	object	No
`url`	Endpoint path appended to the base URL.	string	Yes

Request parameters to send as query, body, or header values.

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`spread`	Merges the value's object entries into the target location instead of setting a single named field.	boolean	No
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Pagination position carried over from the previous page request.

Field	Description	Type	Required
`position`	Numeric offset or page position carried over from the previous page.	union	No
`token`	Cursor token from the previous page used to fetch the next one.	union	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

Controls how subsequent pages are requested.

Field	Description	Type	Required
`condition`	A JEXL expression that continues pagination only while it evaluates true.	string	No
`in`	Where the pagination field is sent: query or body. Allowed: `query`, `body`	enum	Yes
`key`	Request field name that carries the page token, offset, or number.	string	Yes
`maxPage`	Highest page number allowed in `page` mode. Requesting a higher page fails the step with an error.	integer	No
`mode`	Pagination strategy. `cursor` sends the returned next token back as the key and stops when none returns. `offset` advances the key by the number of records consumed. `page` increments the page number and stops on an empty or repeated page. Every mode also stops once `page_size` records are gathered or `iterator.condition` is false. Allowed: `cursor`, `offset`, `page`	enum	No
`startOffset`	First record offset to request. Valid only in offset mode. Defaults to `0`; set to `1` for APIs that count records from 1, such as SCIM's `startIndex`.	integer	No
`startPage`	First page number to request. Valid only in page mode.	integer	No

Controls how each page response is parsed and paginated.

Field	Description	Type	Required
`dataKey`	Path to the records array in the response. A path that resolves to a non-array or resolves to nothing is treated as an empty page, so the step succeeds with the records collected so far and logs a warning.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No
`nextKey`	Path to the next-page token or cursor in the response.	string	No
`nextKeyIn`	Where the next-page token is read from: the response data or headers. Allowed: `data`, `headers`	enum	No

Generates a signed SAML assertion and merges it into the request body for token exchange.

Field	Description	Type	Required
`audience`	Intended audience for the assertion.	string	No
`cert`	Signing certificate for the SAML assertion.	any	No
`clientId`	Client identifier included as the api_key attribute in the assertion.	string	Yes
`issuer`	Issuer identifier declared in the assertion.	string	No
`key`	Base64-encoded private key used to sign the SAML assertion.	string	Yes
`lifetime`	Assertion validity window in seconds.	number	No
`nameId`	Subject NameID identifying the authenticating principal.	string	No
`nameIdentifierFormat`	Format URI for the subject NameID.	string	No
`objectKey`	Request body key under which the generated base64 SAML assertion is placed.	string	Yes
`tokenEndpoint`	Recipient token endpoint the assertion is addressed to.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="paginated_request" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	Records accumulated across the fetched pages.	any	No
`message`	Status or error message from the response.	string	No
`next`	Pagination cursor for the next page, or null when no further pages remain.	union	No
`position`	Numeric offset or page position reached, for offset and page pagination modes.	number	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="paginated_request" version="v1" kind="output" */} # request Source: https://docs.stackone.com/connector-yaml-reference/step-functions/request Step function: request Sends an HTTP request to the provider's API and returns the response. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="request" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Request parameters to send as query, body, or header values.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for this request.	string	No
`cacheTTL`	Minutes to serve this request from the shared per-account response cache. 0 or omitted disables caching.	integer	No
[`certificates`](#certificates)	Client TLS certificates and keys for mutual TLS connections.	object	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`encodeQueryParams`	Whether to URL-encode query parameter values before sending.	boolean	No
`method`	HTTP method to use: get, post, put, patch, or delete. Allowed: `get`, `post`, `put`, `delete`, `patch`	enum	Yes
[`response`](#response)	Controls how the raw response is parsed into step output data.	object	No
[`saml`](#saml)	Generates a signed SAML assertion and merges it into the request body for token exchange.	object	No
`url`	Endpoint path appended to the base URL.	string	Yes

Request parameters to send as query, body, or header values.

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`inline`	Sends the string value as the raw request body. Valid only as the sole in: body argument.	boolean	No
`name`	Name of the request parameter.	string	Yes
`spread`	Merges the value's object entries into the target location instead of setting a single named field.	boolean	No
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Client TLS certificates and keys for mutual TLS connections.

Field	Description	Type	Required
`certs`	PEM-encoded client certificates for mutual TLS. Each entry is a raw or base64-encoded PEM certificate.	string[]	No
`keys`	PEM-encoded client private keys for mutual TLS. Each entry is a raw or base64-encoded PEM private key.	string[]	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

Controls how the raw response is parsed into step output data.

Field	Description	Type	Required
`collection`	Whether to treat the response payload as a collection of records to index.	boolean	No
`dataKey`	Path to the field in the response holding the records to extract.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No

Generates a signed SAML assertion and merges it into the request body for token exchange.

Field	Description	Type	Required
`audience`	Intended audience for the assertion.	string	No
`cert`	Signing certificate for the SAML assertion.	any	No
`clientId`	Client identifier included as the api_key attribute in the assertion.	string	Yes
`issuer`	Issuer identifier declared in the assertion.	string	No
`key`	Base64-encoded private key used to sign the SAML assertion.	string	Yes
`lifetime`	Assertion validity window in seconds.	number	No
`nameId`	Subject NameID identifying the authenticating principal.	string	No
`nameIdentifierFormat`	Format URI for the subject NameID.	string	No
`objectKey`	Request body key under which the generated base64 SAML assertion is placed.	string	Yes
`tokenEndpoint`	Recipient token endpoint the assertion is addressed to.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="request" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The parsed response payload extracted from the provider response.	any	No
`message`	Status or error message from the response.	string	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="request" version="v1" kind="output" */} # sign_jwt Source: https://docs.stackone.com/connector-yaml-reference/step-functions/sign-jwt Step function: sign_jwt Signs a JWT with a private key, for later requests to use as a credential. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="sign_jwt" */} ## Input

Field	Description	Type	Required
`algorithm`	Signing algorithm. Only RS256 is supported.	string	Yes
`claims`	Claims to include in the JWT payload, such as `iss`, `scope`, and `aud`. `iat` and `exp` are required numbers with `exp` after `iat`, and accept `now` or `now+<N>s\|m\|h` tokens.	object	Yes
`privateKey`	PEM-encoded private key used to sign the token.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="sign_jwt" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`expiresIn`	Token lifetime in seconds.	number	Yes
`publicKeyFingerprint`	Fingerprint of the public key matching the signing key.	string	Yes
`token`	The signed JWT.	string	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="sign_jwt" version="v1" kind="output" */} # soap_paginated_request Source: https://docs.stackone.com/connector-yaml-reference/step-functions/soap-paginated-request Step function: soap_paginated_request Sends SOAP requests to a paginated endpoint until it has one page of results, then returns a cursor for the next page. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="soap_paginated_request" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Request parameters to send as query, body, or header values.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the SOAP service.	string	No
[`cursor`](#cursor)	Pagination position carried over from the previous page request.	object	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`encodeQueryParams`	Whether to URL-encode query parameter values before sending.	boolean	No
`envelope`	SOAP envelope template, as a string or object, used to build the request body.	union	No
[`iterator`](#iterator)	Controls how subsequent pages are requested.	object	Yes
`method`	HTTP method to use for the SOAP call, typically post. Allowed: `get`, `post`, `put`, `delete`, `patch`	enum	Yes
[`namespaces`](#namespaces)	XML namespace declarations added to the SOAP envelope.	object[]	No
[`response`](#response)	Controls how each page response is parsed and paginated.	object	No
`soapAction`	Value sent in the SOAPAction HTTP header.	string	No
`soapOperation`	Name of the SOAP operation to invoke.	string	No
`url`	SOAP endpoint path appended to the base URL.	string	Yes
`useSoapContext`	Whether to wrap the request using the SOAP context. Default: `true`	boolean	Yes

Request parameters to send as query, body, or header values.

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`type`	Selects no authentication.	string	Yes

Field	Description	Type	Required
`encoding`	Encoding applied to the username and password, such as base64.	string	No
`password`	Password for basic authentication.	string	No
`type`	Selects HTTP basic authentication.	string	Yes
`username`	Username for basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Whether to prefix the token with `Bearer ` in the header. Defaults to true. Default: `true`	boolean	Yes
`token`	Bearer token sent with the request.	string	Yes
`type`	Selects bearer token authentication.	string	Yes

Field	Description	Type	Required
`includeBearer`	Whether to prefix the token with `Bearer ` in the header. Defaults to true. Default: `true`	boolean	Yes
`token`	OAuth 2.0 access token sent with the request.	string	Yes
`type`	Selects OAuth 2.0 authentication.	string	Yes

Pagination position carried over from the previous page request.

Field	Description	Type	Required
`position`	How far into the previous page was read, so this request resumes from there.	union	No
`token`	Cursor token from the previous page used to fetch the next one.	union	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

Controls how subsequent pages are requested.

Field	Description	Type	Required
`in`	Where the pagination field is sent: query or body. Allowed: `query`, `body`	enum	Yes
`key`	Request field name that carries the page token or number.	string	Yes

XML namespace declarations added to the SOAP envelope.

Field	Description	Type	Required
`namespace`	Namespace URI bound to the prefix.	string	Yes
`namespaceIdentifier`	XML namespace prefix.	string	Yes

Controls how each page response is parsed and paginated.

Field	Description	Type	Required
`collection`	Currently not in use.	boolean	No
`dataKey`	Path to the records array within the response.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No
`nextKey`	Path to the next-page token or cursor in the response.	string	No
`nextKeyIn`	Where the next-page token is read from: the response data or headers. Allowed: `data`, `headers`	enum	No

Field	Description	Type	Required
`data`	Records accumulated across the fetched pages.	any	No
`message`	Status or error message from the response.	string	No
`next`	Cursor token for the next page. Null means the next request continues from `position` in the current page, and it is omitted when no pages remain.	union	No
`position`	How far into the current page has been read, saved in the cursor so the next request resumes from there.	number	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="soap_paginated_request" version="v1" kind="output" */} # soap_request Source: https://docs.stackone.com/connector-yaml-reference/step-functions/soap-request Step function: soap_request Sends a SOAP request to the provider and returns the parsed response. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="soap_request" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Request parameters to send as query, body, or header values.	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the SOAP service.	string	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`encodeQueryParams`	Whether to URL-encode query parameter values before sending.	boolean	No
`envelope`	SOAP envelope template, as a string or object, used to build the request body.	union	No
`method`	HTTP method to use for the SOAP call, typically post. Allowed: `get`, `post`, `put`, `delete`, `patch`	enum	Yes
[`namespaces`](#namespaces)	XML namespace declarations added to the SOAP envelope.	object[]	No
[`response`](#response)	Controls how the raw response is parsed into step output data.	object	No
`soapAction`	Value sent in the SOAPAction HTTP header.	string	No
`soapOperation`	Name of the SOAP operation to invoke.	string	No
`url`	SOAP endpoint path appended to the base URL.	string	Yes
`useSoapContext`	Whether to wrap the request using the SOAP context. Default: `true`	boolean	Yes

Request parameters to send as query, body, or header values.

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

XML namespace declarations added to the SOAP envelope.

Field	Description	Type	Required
`namespace`	Namespace URI bound to the prefix.	string	Yes
`namespaceIdentifier`	XML namespace prefix.	string	Yes

Controls how the raw response is parsed into step output data.

Field	Description	Type	Required
`collection`	Whether to treat the response payload as a collection of records to index.	boolean	No
`dataKey`	Top-level response key holding the records to extract.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="soap_request" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The parsed response payload extracted from the SOAP response.	any	No
`message`	Status or error message from the response.	string	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="soap_request" version="v1" kind="output" */} # static_values Source: https://docs.stackone.com/connector-yaml-reference/step-functions/static-values Step function: static_values Returns fixed values, or the result of an expression. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="static_values" */} ## Input

Field	Description	Type	Required
`values`	Static values to return, as an object, an array, or an expression string.	union	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="static_values" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The static values returned by the step.	any	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="static_values" version="v1" kind="output" */} # typecast Source: https://docs.stackone.com/connector-yaml-reference/step-functions/typecast Step function: typecast Converts fields in source data to their declared types. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="typecast" */} ## Input

Field	Description	Type	Required
`dataSource`	Reference to the source data to cast.	string	Yes
`fields`	Definitions of the fields to cast.	array	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="typecast" version="v2" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The source data with fields cast to their target types.	any	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="typecast" version="v2" kind="output" */} # upload_binary Source: https://docs.stackone.com/connector-yaml-reference/step-functions/upload-binary Step function: upload_binary Uploads raw binary content to the provider. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="upload_binary" */} ## Input

Field	Description	Type	Required
[`args`](#args)	Additional request parameters (query params, headers)	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the upload.	string	No
[`binaryContent`](#binarycontent)	Raw binary content for octet-stream uploads	object	Yes
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
`method`	HTTP method to use for the upload. Allowed: `get`, `post`, `put`, `delete`, `patch` Default: `post`	enum	Yes
[`response`](#response)	Controls how the raw response is parsed into step output data.	object	No
`url`	Upload endpoint path appended to the base URL.	string	Yes

Additional request parameters (query params, headers)

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`spread`	Merges the value's object entries into the target location instead of setting a single named field.	boolean	No
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Raw binary content for octet-stream uploads

Field	Description	Type	Required
`content`	The file content as base64 encoded string	string	Yes
`contentType`	The MIME type for the binary content (defaults to application/octet-stream)	string	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

Controls how the raw response is parsed into step output data.

Field	Description	Type	Required
`collection`	Whether to treat the response payload as a collection of records to index.	boolean	No
`dataKey`	Top-level response key holding the records to extract.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="upload_binary" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The parsed response payload from the upload.	any	No
`message`	Status or error message from the response.	string	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="upload_binary" version="v1" kind="output" */} # upload_file Source: https://docs.stackone.com/connector-yaml-reference/step-functions/upload-file Step function: upload_file Uploads a file to the provider as a multipart form. {/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionDescription name="upload_file" */} ## Input

Field	Description	Type	Required
[`additionalFields`](#additionalfields)	Additional form fields to include in the multipart request	object[]	No
[`args`](#args)	Additional request parameters (query params, headers)	object[]	No
[`authorization`](#authorization)	Overrides the connector's default authentication for this request.	union	No
`baseUrl`	Overrides the connector's base URL for the upload.	string	No
[`customErrors`](#customerrors)	Remaps matching provider error responses to different statuses or messages.	object[]	No
[`file`](#file)	The file to upload	object	Yes
`method`	HTTP method to use for the upload. Allowed: `get`, `post`, `put`, `delete`, `patch` Default: `post`	enum	Yes
[`response`](#response)	Controls how the raw response is parsed into step output data.	object	No
`url`	Upload endpoint path appended to the base URL.	string	Yes

Additional form fields to include in the multipart request

Field	Description	Type	Required
`condition`	A JEXL expression that includes the field only when it evaluates true.	string	No
`contentType`	The MIME type for this form field (e.g., "application/json")	string	No
`name`	Name of the form field.	string	Yes
`value`	Value of the form field.	any	Yes

Additional request parameters (query params, headers)

Field	Description	Type	Required
`arrayFormat`	How array values are serialized in the query string: repeat, brackets, comma, or stringify. Allowed: `repeat`, `brackets`, `comma`, `stringify`	enum	No
`condition`	A JEXL expression that includes the parameter only when it evaluates true.	string	No
`in`	Where to send the parameter: query, body, or headers. Allowed: `query`, `body`, `headers`	enum	Yes
`name`	Name of the request parameter.	string	Yes
`spread`	Merges the value's object entries into the target location instead of setting a single named field.	boolean	No
`value`	Value of the parameter. Supports expressions.	any	Yes

Overrides the connector's default authentication for this request.

Field	Description	Type	Required
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
[`signing`](#authorization-none-signing)	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
`type`	Sends requests without an authorization header.	string	Yes

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

Field	Description	Type	Required
`region`	AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.	string	No
`service`	AWS service name used in the signing credential scope. For example `s3` or `execute-api`.	string	Yes
`strategy`	Signs requests with AWS Signature Version 4.	string	Yes

Field	Description	Type	Required
`algorithm`	Hash algorithm for the HMAC signature. Defaults to `sha256`. Allowed: `sha1`, `sha256`, `sha512`	enum	No
`dateFormat`	Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`. Allowed: `iso8601`, `rfc2822`	enum	No
`headerName`	Header the signature is written into. Defaults to `X-Signature`.	string	No
`includeBodyHash`	Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.	boolean	No
`includeHost`	Include the request hostname in the signed canonical string. Defaults to `false`.	boolean	No
`outputFormat`	Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header. Allowed: `header`, `basic`	enum	No
`prefix`	Prefix prepended to the signature value in the header. Defaults to `hmac-<algorithm>`.	string	No
`strategy`	Signs requests with an HMAC signature over a canonical request string.	string	Yes
`username`	Username paired with the signature when `outputFormat` is `basic`.	string	No

Field	Description	Type	Required
`encoding`	Encoding applied to the `username:password` pair. Defaults to `base64`.	string	No
`password`	Password for HTTP Basic authentication.	string	No
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`type`	Configures HTTP Basic authentication.	string	Yes
`username`	Username for HTTP Basic authentication.	string	No

Field	Description	Type	Required
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`redirectUri`	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
`token`	Token sent on each request. Supports expressions.	string	Yes
`type`	Configures bearer token authentication.	string	Yes

Field	Description	Type	Required
`additionalTokenFields`	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
`authorizationParams`	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
`authorizationUrl`	Provider authorization endpoint where the user grants access.	string	No
`callbackParams`	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
`customHeaders`	Additional HTTP headers sent with token endpoint requests.	object	No
`includeBearer`	Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`. Default: `true`	boolean	Yes
`issuer`	OpenID Connect issuer identifier for the provider.	string	No
`pkce`	Enable PKCE for the authorization code flow.	boolean	No
`redirectUri`	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
`scopeDelimiter`	Delimiter used to separate scopes when requesting authorization.	string	No
`scopes`	OAuth scopes requested during authorization.	string	No
`token`	Expression that resolves the access token sent on each request.	string	Yes
`tokenExpiresIn`	Access token lifetime in seconds.	number	No
`tokenParams`	Extra parameters sent to the token endpoint. Values support expressions.	object	No
`tokenRefreshExpiresIn`	Refresh token lifetime in seconds.	number	No
[`tokenResponse`](#authorization-oauth2-tokenresponse)	Adjusts how a non-standard token endpoint response is parsed.	object	No
`tokenUrl`	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
`type`	Configures OAuth 2.0 authentication.	string	Yes

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
`acceptTokenTypes`	Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.	string[]	No
`accessToken`	Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.	string	No
`refreshToken`	Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.	string	No

Field	Description	Type	Required
`condition`	A JEXL expression that applies the remap only when it evaluates true.	string	No
`message`	Error message to return in place of the provider's.	string	No
`receivedStatus`	Provider HTTP status code to match.	number	Yes
`targetStatus`	HTTP status code to return in place of the matched one.	number	Yes

The file to upload

Field	Description	Type	Required
`content`	The file content as base64 encoded string	string	Yes
`contentType`	The MIME type of the file (e.g., "image/png", "application/pdf")	string	No
`fieldName`	The form field name for the file	string	Yes
`filename`	The filename to use in the upload	string	Yes

Controls how the raw response is parsed into step output data.

Field	Description	Type	Required
`collection`	Whether to treat the response payload as a collection of records to index.	boolean	No
`dataKey`	Top-level response key holding the records to extract.	string	No
`indexField`	Field used to key results when returning an indexed map.	string	No

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="upload_file" version="v1" kind="input" */} ## Output

Field	Description	Type	Required
`data`	The parsed response payload from the upload.	any	No
`message`	Status or error message from the response.	string	No
`raw`	The raw provider response before parsing.	any	No
`statusCode`	HTTP status code of the provider response.	number	Yes

{/* AUTO-GENERATED by docs/scripts/schema-reference/expand-mdx.ts. Do not edit by hand. */} {/* schema-reference: StepFunctionParams name="upload_file" version="v1" kind="output" */} # Expression Language Source: https://docs.stackone.com/connector-yaml-reference/expression-language Complete reference for JSONPath, JEXL, and string interpolation expressions in connector YAML StackOne uses the [`@stackone/expressions`](https://www.npmjs.com/package/@stackone/expressions) library to evaluate dynamic values throughout connector YAML files. Three expression formats are available, each suited to different use cases. ## Expression Formats (`$.path`) - Directly accessing values - No transformation needed - Can use value as returned (`${...}`) - Building strings/URLs - Concatenating with static text - Simple variable substitution (`'{{...}}'`) - Setting default values (`??` operator) - Conditional Logic - Complex transformations | Scenario | Format | Example | |----------|--------|---------| | Access a credential value | JSONPath | `$.credentials.apiKey` | | Access an input parameter | JSONPath | `$.inputs.userId` | | Reference step output | JSONPath | `$.steps.fetch.output.data` | | Build a URL with parameters | String Interpolation | `/users/${inputs.id}` | | Dynamic base URL | String Interpolation | `https://${credentials.subdomain}.api.com` | | Provide a default value | JEXL | `'{{inputs.limit ?? 100}}'` | | Conditional argument | JEXL | `'{{present(inputs.filter)}}'` | | Ternary logic | JEXL | `'{{x > 0 ? x : 0}}'` | | String concatenation with logic | JEXL | `'{{inputs.first + " " + inputs.last}}'` | | Enum matching | JEXL | `'{{$.status == "ACTIVE"}}'` | ## JSONPath Expressions When an expression starts with `$`, it is treated as a JSONPath expression. Use this for direct data access without transformation. ### Syntax | Operator | Description | Example | |----------|-------------|---------| | `$` | Root object | `$.user.name` | | `.` | Child operator | `$.user.name` | | `@` | Current object (in filters) | `@.age` | | `*` | Wildcard: all elements/properties | `$.users[*]` | | `..` | Recursive descent | `$..name` | | `[]` | Subscript | `$.users[0]` | | `[,]` | Union | `$.users[0,2]` | | `[start:end:step]` | Array slice | `$.users[0:2]` | | `[?(expression)]` | Filter expression | `$.users[?(@.age > 30)]` | | `()` | Script expression | Custom expressions | ### Available Contexts | Context | Description | Example | |---------|-------------|---------| | `$.credentials` | Authentication credentials | `$.credentials.apiKey` | | `$.inputs` | Action input parameters | `$.inputs.userId` | | `$.context` | Connection context, such as `environment` and `authenticationType` | `$.context.environment` | | `$.steps.{stepId}.output` | Previous step output | `$.steps.fetch_users.output.data` | | `$.iterator` | Current foreach iteration context | `$.iterator.item` | | `$.result` | The action's assembled result | `$.result.id` | **Examples** ```yaml # Simple value access token: $.credentials.apiKey value: $.inputs.employee_id # Step output dataSource: $.steps.fetch_users.output.data # Nested access expression: $.user.address.city # Bracket notation (for keys with special characters) value: $["info/email"] # Array access value: $.steps.get_all_employees.output.data.employees[0].id # Wildcard iterator: $.steps.get_all_employees.output.data.employees[*].id ``` For more details on JSONPath syntax, refer to the [JSONPath specification](https://goessner.net/articles/JsonPath/). ## String Interpolation Use `${...}` syntax to embed values within strings. This is the preferred method for building URLs, composing strings, and simple variable substitution. ### Syntax ``` ${variable.path} ``` The content inside `${...}` supports the same dot-notation paths as JSONPath but without the `$` root prefix. **Examples** ```yaml # URL path parameters url: /users/${inputs.id} url: /users/${inputs.userId}/posts/${inputs.postId} # Dynamic base URLs baseUrl: https://${credentials.subdomain}.api.provider.com baseUrl: https://api.${credentials.region}.provider.com/v2 # OAuth callback URLs redirect_uri: ${apiHostUri}/connect/oauth2/${connector}/callback # Composing strings value: Bearer ${credentials.accessToken} ``` String interpolation only substitutes values. It does not support operators, conditionals, or function calls. Use JEXL expressions for logic. ## JEXL Expressions JEXL (JavaScript Expression Language) expressions are enclosed in double curly brackets `{{expression}}` and support variables, operators, functions, and conditional logic. In YAML, these must be wrapped in single quotes: `'{{...}}'`. ### Operators #### Arithmetic | Operator | Description | Example | Result | |----------|-------------|---------|--------| | `+` | Addition / string concatenation | `{{x + y}}` | `15` | | `-` | Subtraction | `{{x - y}}` | `5` | | `*` | Multiplication | `{{x * 2}}` | `20` | | `/` | Division | `{{x / y}}` | `2` | | `//` | Floor division | `{{7 // 2}}` | `3` | | `%` | Modulus | `{{x % 3}}` | `1` | | `^` | Exponentiation | `{{2 ^ 3}}` | `8` | #### Comparison | Operator | Description | Example | Result | |----------|-------------|---------|--------| | `==` | Equal | `{{x == 10}}` | `true` | | `!=` | Not equal | `{{x != y}}` | `true` | | `>` | Greater than | `{{x > y}}` | `true` | | `>=` | Greater than or equal | `{{x >= 10}}` | `true` | | `<` | Less than | `{{x < 100}}` | `true` | | `<=` | Less than or equal | `{{x <= 10}}` | `true` | | `in` | Element of string or array | `{{x in [1, 2, 3]}}` | `false` | #### Logical | Operator | Description | Example | |----------|-------------|---------| | `!` | Logical NOT | `{{!active}}` | | `&&` | Logical AND | `{{x > 5 && y < 10}}` | | `\|\|` | Logical OR | `{{x < 5 \|\| y > 10}}` | #### Special | Operator | Description | Example | |----------|-------------|---------| | `? :` | Ternary operator | `{{x > 10 ? "big" : "small"}}` | | `??` | Nullish coalescing | `{{x ?? "default"}}` | ### Identifiers and Context Access Access variables from the evaluation context using dot notation: ```yaml # Given context: { name: { first: "John" }, jobs: ["Developer", "Designer"] } '{{name.first}}' # "John" '{{jobs[1]}}' # "Designer" ``` ### Collection Filtering Filter arrays using bracket expressions: ```yaml # Given context: { users: [{ name: "John", age: 30 }, { name: "Jane", age: 25 }] } '{{users[.name == "John"].age}}' # 30 '{{users[.age > 25].name}}' # ["John"] ``` ### Common Patterns in Connector YAML ```yaml # Conditional argument inclusion condition: '{{present(inputs.filter)}}' # Default values value: '{{inputs.limit || 100}}' value: '{{$.inputs.status ?? "active"}}' # Ternary logic value: '{{$.count > 0 ? $.count : 0}}' # String concatenation expression: '{{$.first_name + " " + $.last_name}}' # Null checking with fallback value: '{{present(inputs.cursor) ? inputs.cursor : null}}' # Complex conditionals condition: '{{present(inputs.start_date) && present(inputs.end_date)}}' ``` ### Conditional Arguments Within a step's `args`, attach a `condition` to include an argument only when the condition evaluates to `true`. The most common use of JEXL in connector YAML is omitting optional query parameters, body fields, or headers when the corresponding input is absent. ```yaml args: - name: filter value: '{{inputs.filter}}' in: query condition: '{{present(inputs.filter)}}' - name: updated_since value: $.inputs.updated_after in: query condition: '{{present(inputs.updated_after)}}' - name: include_inactive value: "true" in: query condition: '{{inputs.include_inactive == true}}' ``` --- ## JEXL Functions The expression engine includes a set of built-in functions available in JEXL expressions. ### Presence & Type Checking #### `present(value)` Returns `true` if the value is not null or undefined. This is the most commonly used function in connector YAML for conditional argument inclusion. ```yaml # Include query param only if provided condition: '{{present(inputs.filter)}}' condition: '{{present(inputs.cursor)}}' # Check step output exists condition: '{{present(steps.fetch_data.output.data)}}' ``` | Input | Result | |-------|--------| | `present("hello")` | `true` | | `present(0)` | `true` | | `present([])` | `true` | | `present({})` | `true` | | `present(null)` | `false` | | `present(undefined)` | `false` | #### `missing(value)` Returns `true` if the value is null or undefined. The inverse of `present()`. ```yaml condition: '{{missing(inputs.optional_field)}}' ``` ### String Functions #### `capitalize(value, mode?)` Capitalizes characters in a string. By default capitalizes the first character; use `'each'` mode to capitalize each word. ```yaml value: '{{capitalize(inputs.name)}}' # "john" → "John" value: '{{capitalize(inputs.name, "each")}}' # "john doe" → "John Doe" ``` #### `truncate(value, maxLength, suffix?)` Truncates a string to a maximum length, appending a suffix (default `"..."`). ```yaml value: '{{truncate(inputs.description, 100)}}' # Truncate to 100 chars with "..." value: '{{truncate(inputs.title, 50, "…")}}' # Custom suffix value: '{{truncate(inputs.note, 80, "")}}' # No suffix ``` #### `padStart(value, targetLength, padString?)` Pads the start of a string to reach a target length. Numbers are converted to strings automatically. ```yaml value: '{{padStart(inputs.id, 8, "0")}}' # "42" → "00000042" value: '{{padStart(5, 3, "0")}}' # 5 → "005" ``` #### `encodeBase64(value)` Encodes a string to Base64. ```yaml value: '{{encodeBase64(credentials.apiKey + ":" + credentials.secret)}}' ``` #### `decodeBase64(value)` Decodes a Base64 string. ```yaml value: '{{decodeBase64(inputs.encoded_data)}}' ``` #### `regexMatch(value, pattern, groupIndex?)` Extracts a value from a string using a regular expression. Returns the specified capture group (default: `1`) or `null` if no match. ```yaml # Extract cursor from Link header value: '{{regexMatch(steps.request.output.headers.link, "after=([^&>]+)", 1)}}' # Extract numeric ID value: '{{regexMatch(inputs.reference, "user_id=(\\d+)", 1)}}' # Full match (group 0) value: '{{regexMatch(inputs.text, "World", 0)}}' ``` #### `upper(value)` / `lower(value)` Uppercase or lowercase a string. Returns an empty string for non-string input. ```yaml value: '{{upper(inputs.code)}}' # "abc" → "ABC" value: '{{lower(credentials.subdomain)}}' # "MyOrg" → "myorg" ``` #### `replace(value, search, replacement, replaceAll?)` Replaces occurrences of a substring. By default replaces only the first; pass `true` as the fourth argument to replace all. ```yaml value: '{{replace(inputs.path, " ", "_")}}' # first occurrence value: '{{replace(inputs.path, "-", "_", true)}}' # all occurrences ``` #### `split(value, separator?)` Splits a string into an array (default separator `","`). Returns an empty array for non-string input. ```yaml value: '{{split(inputs.fields)}}' # "a,b,c" → ["a", "b", "c"] value: '{{split(inputs.tags, " ")}}' # "a b c" → ["a", "b", "c"] ``` #### `asString(value)` Converts any value to its string representation (objects/arrays are JSON-stringified). Returns `""` for null/undefined. ```yaml value: '{{asString(inputs.count)}}' # 42 → "42" value: '{{asString(inputs.filter)}}' # { a: 1 } → '{"a":1}' ``` #### `decodeUri(value)` Decodes a URI-encoded string (percent-decoding). Useful for pre-encoded values like pagination cursors that would otherwise be double-encoded. ```yaml value: '{{decodeUri(steps.request.output.data.next_cursor)}}' # "a%3Db" → "a=b" ``` #### `urlParam(url, paramName)` Extracts a query-parameter value from a URL string. Returns `null` if the param is absent or inputs are invalid. ```yaml # Pull the next page number out of a `next` URL value: '{{urlParam(steps.request.output.data.paging.next, "page")}}' ``` | Input | Result | |-------|--------| | `urlParam("https://api.x.com/items?page=2&limit=10", "page")` | `"2"` | | `urlParam("https://api.x.com/items?page=2", "missing")` | `null` | ### Crypto Functions #### `sha256(value, encoding?)` Computes the SHA-256 hash of a string. Useful for request signing and content verification. - `value` (string): The string to hash - `encoding` (string, optional): `'hex'` (default) or `'base64'` - Returns: hash string, or empty string for invalid input ```yaml value: '{{sha256(inputs.body)}}' value: '{{sha256(inputs.body, "base64")}}' ``` | Input | Result | |-------|--------| | `sha256("hello")` | `"2cf24dba5fb0a30e..."` (64-char hex) | | `sha256("hello", "base64")` | `"LPJNul+wow4m6Dsq..."` (base64) | | `sha256(null)` | `""` | #### `hmacSha256(value, key, encoding?)` Computes an HMAC-SHA256 signature using a secret key. Used for webhook signature verification and API request signing. - `value` (string): The string to sign - `key` (string): The secret key - `encoding` (string, optional): `'hex'` (default) or `'base64'` - Returns: HMAC digest, or empty string for invalid input ```yaml value: '{{hmacSha256(inputs.body, credentials.signingSecret)}}' value: '{{hmacSha256(inputs.body, credentials.signingSecret, "base64")}}' ``` | Input | Result | |-------|--------| | `hmacSha256("hello", "secret")` | `"88aab3ede8d3adf9..."` (64-char hex) | | `hmacSha256("hello", "secret", "base64")` | base64-encoded HMAC | | `hmacSha256(null, "secret")` | `""` | | `hmacSha256("hello", null)` | `""` | #### `md5(value, encoding?)` Computes the MD5 hash of a string. - `value` (string): The string to hash - `encoding` (string, optional): `'hex'` (default) or `'base64'` - Returns: hash string, or empty string for invalid input ```yaml value: '{{md5(inputs.body)}}' value: '{{md5(inputs.body, "base64")}}' ``` | Input | Result | |-------|--------| | `md5("hello")` | `"5d41402abc4b2a76b9719d911017c592"` | | `md5("hello", "base64")` | `"XUFAKrxLKna5cZ2REBfFkg=="` | | `md5(null)` | `""` | --- ### Array Functions #### `includes(array, value)` Checks if an array includes a value. If `value` is an array, checks that ALL values are included. ```yaml condition: '{{includes(inputs.roles, "admin")}}' condition: '{{includes(inputs.scopes, ["read", "write"])}}' # All must match ``` #### `includesSome(array, value)` Checks if an array includes AT LEAST ONE of the given values. ```yaml condition: '{{includesSome(inputs.tags, ["urgent", "critical"])}}' ``` #### `dedupe(array)` Removes duplicate entries from an array, preserving order. Works with primitives and objects (compared by content with sorted keys). ```yaml value: '{{dedupe(steps.merge_data.output.data.ids)}}' ``` | Input | Result | |-------|--------| | `dedupe([1, 2, 2, 3, 1])` | `[1, 2, 3]` | | `dedupe(["a", "b", "a"])` | `["a", "b"]` | | `dedupe([{id: 1}, {id: 2}, {id: 1}])` | `[{id: 1}, {id: 2}]` | #### `join(array, separator?)` Joins array elements into a string with a separator (default: `","`). Filters out null/undefined values. ```yaml value: '{{join(inputs.fields, ",")}}' value: '{{join(inputs.tags, " - ")}}' value: '{{join(["first", "last"], " ")}}' ``` | Input | Result | |-------|--------| | `join(["a", "b", "c"])` | `"a,b,c"` | | `join(["a", "b"], " - ")` | `"a - b"` | | `join(["a", null, "b"])` | `"a,b"` | | `join(["a", "b", "c"], "")` | `"abc"` | #### `reduce(array, operation, field?)` Applies an aggregate operation to an array. When `field` is specified, that field is extracted from each object before applying the operation. Supported operations: | Operation | Description | |-----------|-------------| | `"sum"` | Adds all numeric values | | `"avg"` | Averages all numeric values | | `"count"` | Returns the number of items | | `"min"` | Returns the smallest numeric value | | `"max"` | Returns the largest numeric value | | `"concat"` | Extracts an array field from each object (requires `field`) and concatenates the results into a single flat array | | `"flatten"` | Flattens one level of nesting when the array elements are themselves arrays (no `field` needed) | ```yaml # Sum an array of numbers value: '{{reduce([1, 2, 3], "sum")}}' # 6 # Sum a field across objects value: '{{reduce(steps.fetch.output.data.items, "sum", "price")}}' # Average a field across objects value: '{{reduce(steps.fetch.output.data.scores, "avg", "value")}}' # 85 # Count items value: '{{reduce(steps.fetch.output.data.records, "count")}}' # Concatenate nested arrays from a field value: '{{reduce(steps.fetch.output.data.items, "concat", "tags")}}' # ["a", "b", "c"] # Flatten an array of arrays (no field required) value: '{{reduce([[1, 2], [3, 4]], "flatten")}}' # [1, 2, 3, 4] ``` | Input | Result | |-------|--------| | `reduce([1, 2, 3], "sum")` | `6` | | `reduce([{v: 10}, {v: 20}], "sum", "v")` | `30` | | `reduce([{v: 80}, {v: 90}], "avg", "v")` | `85` | | `reduce([1, 2, 3], "count")` | `3` | | `reduce([{v: 1}, {v: 3}], "max", "v")` | `3` | | `reduce([{t: ["a"]}, {t: ["b"]}], "concat", "t")` | `["a", "b"]` | | `reduce([[1, 2], [3, 4]], "flatten")` | `[1, 2, 3, 4]` | | `reduce(null, "sum")` | `null` | #### `min(...values)` Returns the smallest number from the arguments. Accepts either individual values or a single array. Returns `null` when no valid numbers are provided. ```yaml value: '{{min(inputs.page_size, 100)}}' # cap page size at 100 value: '{{min(steps.fetch.output.data.prices)}}' # smallest of an array ``` | Input | Result | |-------|--------| | `min(1, 2, 3)` | `1` | | `min([5, 2, 8])` | `2` | | `min(42)` | `42` | ### Object Functions #### `keys(object)` Returns the keys of an object as an array. Returns empty array for non-objects. ```yaml value: '{{keys(steps.fetch_data.output.data.metadata)}}' ``` #### `values(object)` Returns the values of an object as an array. Returns empty array for non-objects. ```yaml value: '{{values(steps.fetch_data.output.data.attributes)}}' ``` #### `zipObject(keys, values)` Combines two parallel arrays into an object by pairing `keys[i]` with `values[i]`. If the arrays are different lengths, extra elements from the longer array are ignored. Non-string keys are skipped. Returns `{}` if either input is missing or not an array. ```yaml # Build an object from field names and values value: '{{zipObject(steps.fetch.output.data.fields, steps.fetch.output.data.values)}}' # Combine static keys with dynamic values value: '{{zipObject(["name", "email"], [inputs.name, inputs.email])}}' ``` | Input | Result | |-------|--------| | `zipObject(["a", "b"], [1, 2])` | `{a: 1, b: 2}` | | `zipObject(["name", "email"], ["John", "john@example.com"])` | `{name: "John", email: "john@example.com"}` | | `zipObject(["a", "b", "c"], [1, 2])` | `{a: 1, b: 2}` | | `zipObject([], [])` | `{}` | | `zipObject(null, [1, 2])` | `{}` | #### `groupBy(array, key)` Array utility that groups items but returns an object result; it's documented here alongside object helpers for convenience (see the Array Functions section for related utilities). Groups an array of objects by the value of a specified key, producing an object where each unique key value maps to an array of matching items. Items without the key or with a null/undefined value for that key are collected under `"__missing__"`. Returns `{}` if the input is missing, not an array, or the key is not a string. ```yaml # Group employees by department value: '{{groupBy(steps.fetch.output.data.employees, "department")}}' # Group by status value: '{{groupBy(steps.fetch.output.data.records, "status")}}' ``` | Input | Result | |-------|--------| | `groupBy([{dept: "eng", name: "Alice"}, {dept: "hr", name: "Bob"}, {dept: "eng", name: "Carol"}], "dept")` | `{eng: [{...}, {...}], hr: [{...}]}` | | `groupBy([{status: "active"}, {status: "inactive"}, {status: "active"}], "status")` | `{active: [{...}, {...}], inactive: [{...}]}` | | `groupBy([{name: "Alice"}, {status: "active"}], "status")` | `{__missing__: [{name: "Alice"}], active: [{status: "active"}]}` | | `groupBy(null, "key")` | `{}` | #### `parseJson(value)` Parses a JSON string into its decoded value (object, array, or primitive). Returns `null` on missing/non-string/empty/invalid input. Useful when a provider delivers a field as a JSON-encoded string (e.g. inside a form-urlencoded webhook body). ```yaml # Decode a JSON-encoded `payload` form field from a webhook body value: '{{parseJson(inputs.payload)}}' ``` | Input | Result | |-------|--------| | `parseJson('{"id":"abc"}')` | `{ id: "abc" }` | | `parseJson('[1,2,3]')` | `[1, 2, 3]` | | `parseJson("not json")` | `null` | ### Date Functions Date-time values with no UTC offset are resolved in the host timezone. Prefer offset-bearing input (e.g. `...Z` or `+00:00`) when the exact instant matters. #### `now()` Returns the current date/time in ISO 8601 format. ```yaml value: '{{now()}}' # "2025-04-10T12:00:00.000Z" ``` #### `yearsElapsed(startDate, format, endDate?)` Calculates the number of complete years between two dates. If `endDate` is omitted, uses today. ```yaml value: '{{yearsElapsed(inputs.hire_date, "yyyy-MM-dd")}}' value: '{{yearsElapsed("2015-01-01", "yyyy-MM-dd", "2025-01-01")}}' # 10 ``` #### `hasPassed(date, format, yearsToAdd?)` Checks whether a date (optionally with years added) has already passed. ```yaml condition: '{{hasPassed(inputs.expiry_date, "yyyy-MM-dd")}}' condition: '{{hasPassed(inputs.start_date, "yyyy-MM-dd", 5)}}' # Has start + 5 years passed? ``` #### `nextAnniversary(initialDate, format)` Calculates the next anniversary of a date. ```yaml value: '{{nextAnniversary(inputs.hire_date, "dd/MM/yyyy")}}' ``` #### `deltaFromNowMs(dateInput, format?)` Calculates milliseconds between a date and now. Supports ISO strings (default), Unix timestamps (`'timestamp'`), and seconds (`'seconds'`). ```yaml value: '{{deltaFromNowMs(inputs.expires_at)}}' value: '{{deltaFromNowMs(inputs.timestamp, "timestamp")}}' ``` #### `unixToIso(value, unit?)` Converts a Unix epoch timestamp to an ISO-8601 date-time string. Accepts epoch `'seconds'` (default) or `'ms'`, as a number or numeric string. Returns `null` for non-numeric / out-of-range input. Useful when a provider returns epoch timestamps but the defined schema expects a date-time string. ```yaml value: '{{unixToIso(steps.fetch.output.data.created_at)}}' # seconds value: '{{unixToIso(steps.fetch.output.data.created_ms, "ms")}}' # milliseconds ``` | Input | Result | |-------|--------| | `unixToIso(1769518356)` | `"2026-01-27T12:52:36.000Z"` | | `unixToIso(1769518356722, "ms")` | `"2026-01-27T12:52:36.722Z"` | | `unixToIso("not-a-number")` | `null` | #### `isoToUnix(value, unit?)` The inverse of `unixToIso` — converts a date-time string to a Unix epoch timestamp. Returns epoch `'seconds'` (default, floored) or `'ms'`; `null` for unparsable input. ```yaml value: '{{isoToUnix(inputs.updated_at)}}' # → epoch seconds value: '{{isoToUnix(inputs.updated_at, "ms")}}' # → epoch milliseconds ``` #### `formatDate(value, formatString)` Formats a date-time value into a string using a token-based format. Output is rendered in UTC, so numeric offset tokens and instant fields are stable across host timezones. Accepts an ISO 8601 string (with or without offset) or one of these fallback formats: `yyyy-MM-dd`, `yyyy/MM/dd`, `dd/MM/yyyy`, `dd-MM-yyyy`, `yyyy-dd-MM`, `yyyy/dd/MM`, `MM/dd/yyyy`, `MM-dd-yyyy`. For epoch numbers, compose with `unixToIso` first. **Common tokens** | Token | Meaning | Example | |-------|---------|---------| | `yyyy` | 4-digit calendar year | `2026` | | `MM` | 2-digit month (01–12) | `01` | | `MMM` | Abbreviated month name | `Jan` | | `MMMM` | Full month name | `January` | | `dd` | 2-digit day of month | `27` | | `do` | Day of month, ordinal | `27th` | | `EEE` | Abbreviated weekday | `Tue` | | `EEEE` | Full weekday | `Tuesday` | | `HH` | Hour (00–23) | `12` | | `hh` | Hour (01–12) | `12` | | `mm` | Minutes (00–59) | `52` | | `ss` | Seconds (00–59) | `36` | | `SSS` | Milliseconds | `722` | | `a` | AM/PM marker | `PM` | | `xxx` | Numeric offset (`+00:00`) | `+00:00` | | `X` | Short offset (`Z` for UTC) | `Z` | | `'text'` | Literal text (wrap in single quotes) | `at` | ```yaml # Date only value: '{{formatDate(inputs.created_at, "yyyy-MM-dd")}}' # "2026-01-27" # SQL-style datetime value: '{{formatDate(inputs.created_at, "yyyy-MM-dd HH:mm:ss")}}' # "2026-01-27 12:52:36" # HTTP Date header (RFC 1123) value: '{{formatDate(inputs.created_at, "EEE, dd MMM yyyy HH:mm:ss ''GMT''")}}' # Format the current instant value: '{{formatDate(now(), "yyyy-MM-dd")}}' # today, e.g. "2026-01-27" # Compose with unixToIso for epoch input value: '{{formatDate(unixToIso(steps.fetch.output.data.created_at), "yyyy-MM-dd")}}' ``` | Input | Result | |-------|--------| | `formatDate("2026-01-27T12:52:36.722Z", "yyyy-MM-dd")` | `"2026-01-27"` | | `formatDate("2026-01-27T12:52:36.722Z", "HH:mm:ss")` | `"12:52:36"` | | `formatDate("2026-01-27T12:52:36.722Z", "EEE, dd MMM yyyy")` | `"Tue, 27 Jan 2026"` | | `formatDate("not-a-date", "yyyy-MM-dd")` | `null` | **Case matters.** Lowercase `mm` is minutes; uppercase `MM` is month (`yyyy-mm-dd` silently renders `"2026-52-27"`). Uppercase `YYYY`-`MM`-`DD` (the SQL/ISO convention) returns `null`. Use `yyyy-MM-dd` instead. For epoch timestamps, use `isoToUnix(value)` instead of the `t`/`T` tokens. ### Advanced Functions #### `parseJson`, XML & webhook helpers A few functions exist for specialized transport/webhook scenarios: | Function | Purpose | |----------|---------| | `wrapXmlArray(value, wrapperElement?, typeAttribute?)` | Wraps an array so it serializes correctly for XML APIs (used with SOAP/XML request bodies via `fast-xml-parser`). | | `webhookEventsUrl(webhooksUrl, orgId, projectSecureId, connectorProfileId, token?)` | Builds the StackOne events webhook URL (with a base64url-encoded routing context) for provisioning native provider webhooks. Used inside `events.setup` steps. | These appear in generated webhook setup and XML/SOAP connectors. ## Validation and Error Handling ### `isValidExpression(expression)` The expression engine validates syntax before evaluation. Invalid expressions return errors that help identify issues. ### Incremental JSONPath Errors When using the expression engine with `incrementalJsonPath: true`, detailed error messages are provided for JSON Path evaluation failures: ``` Key 'age' not found at '$.user.details'. Available keys: name ``` This is used internally by StackOne Agent for self-repair during connector development. ### Safe Evaluation The `safeEvaluate` function returns `null` instead of throwing errors, which is useful for optional expressions and fallback patterns. # Embed Source: https://docs.stackone.com/embed/overview Bring StackOne into your product or your agent. Embed StackOne in your product: ship integrations and agent actions to your own customers, under your brand. Your customers connect the tools they already use. Your product or agent acts on them. ## What are you building? I'm building an application and my customers need to connect the tools they already use. I'm building an agent and it needs to act on real business systems. ## Want to connect data to your agent? If you just need to connect data sources to your agent, you don't need any of the above. Start here. I want to connect my AI agent to a system I already use and run my first actions. # Getting Started Source: https://docs.stackone.com/embed/getting-started The path to embedding StackOne in your product, from setup to production. Bring StackOne into your own product: connect your users' accounts and call connector actions from your code. Here's the path end to end. Just exploring, or prefer a no-code route? Start with the [Quickstart](/gateway/quickstart) to connect your first connector from the dashboard. Create a project and an API key with the scopes **Actions** and **Platform API**. This **API key** will be used to authenticate all backend and API calls below. A Connector Profile configures a provider's authentication and the actions your users can use. This sets up a [**connector profile**](/gateway/concepts/connector-profiles) for the provider you chose (e.g. `hubspot`) — its authentication and enabled actions — which you target when creating a session. Instantiate a connect session on your backend to open the linking flow for a specific user. Using your **API key** and **provider** from the previous steps, this returns a short-lived **session token** for the frontend. Open the Hub or send an Auth Link so users connect their accounts. React to accounts being linked, updated, or disconnected. The Hub is initiated using the **session token**. Once a user links an account, the Hub returns its **account ID** (or you pick it up from the **account event**) for calling actions. Use the Agent SDK, MCP, A2A, or RPC/HTTP, whichever fits your stack. Every call uses your **API key** and the **account ID** from the previous step, selecting which [linked account](/gateway/concepts/linked-accounts) to act on. ## Before you go to production Your brand on the consent screen and dedicated rate limits. React to account and data changes. Inspect calls, debug failures, and watch rate limits. # API Keys Source: https://docs.stackone.com/embed/api-keys Generate and manage a StackOne API key from the dashboard. An API key authenticates every call your backend makes to StackOne. Keys are scoped to a single [project](/gateway/concepts/organizations-and-projects#projects). A key can only reach the connector profiles and linked accounts in the project it was created in. ## Generate an API key Log in to the [StackOne dashboard](https://app.stackone.com) and go to **Project Settings → API Keys** in the left navigation. API Keys management page

Click **Create API key** and enter a name (e.g. `my-agent-key` or `production-hris-sync`). This label can't be changed later. Create API key dialog with scopes

New keys come with a default set of scopes. Expand the **Scopes** section to enable or restrict access for your use case. The [scopes reference](#scopes) below lists what each scope allows. After clicking **Generate**, the key is shown **once**. Copy it immediately and store it securely. Store the key in a password manager or secrets vault. Never commit API keys to source control. ## Scopes An API key's scopes control what it can access. Set them when creating the key; new keys start with the defaults below. | Scope | Default | Grants | |-------|---------|--------| | **Platform API** | Read + Write | Account management, [connect sessions](/embed/connect-session), and connector profiles. Required for [Platform API](/platform-api/overview) operations such as StackOne Connect and account management. | | **Actions** | Execute | Interact with actions via RPC and MCP. | | **Connectors** | Read | Custom connector management. **Read** (`connectors:read`) downloads connectors from the registry; **Write** (`connectors:write`) pushes and deletes them. Required for [connector building](/connector-building/overview) operations. | | **Credentials** | Off | Retrieve stored credentials for direct provider access (read-only). Required for the StackOne CLI and running actions outside the platform. | | **Unified API** | Read + Write | All legacy (unified) endpoints (HRIS, ATS, CRM, LMS, etc.) for reading and writing data across connected providers. | For AI agents, you typically need: **Platform API Read** (list connected accounts), **Actions Execute** (RPC and MCP), **Connectors Read** (download connectors), and **Credentials Read** (direct provider access). ## Key management Your key appears in the **API Keys** table, where you can enable, disable, view scopes for, and delete keys at any time. Usage is tracked. The **Last used** column helps you spot stale keys to revoke. Review the list regularly. ## Next steps Use your key to create a session token and open the account-linking flow for a user. Return to the end-to-end embedding journey. # Connect Session Source: https://docs.stackone.com/embed/connect-session Generate connect session tokens from your backend so your end-users can link their accounts through the Hub. A **connect session** is a short-lived token that authorizes one of your end-users to link an account. Your backend creates it with your [API key](/embed/api-keys), so the key is never exposed to the frontend. **Prerequisites:** a StackOne [API key](/embed/api-keys), and a [connector profile](/gateway/quickstart#setup-connector-profile) enabled for the provider you're connecting. ## Create a session Call the [Connect Sessions endpoint](/platform/api-reference/connect-sessions/create-connect-session) from your backend. Two fields are **required**: - **`origin_owner_id`**: your identifier for the customer's organization - **`origin_owner_name`**: a human-readable name for that organization, stored against the account Always set `origin_owner_id` server-side. Never pass it through from a client-side request, or a customer could claim another customer's linked accounts. ```typescript TypeScript SDK import { StackOne } from "@stackone/stackone-client-ts"; const stackOne = new StackOne({ security: { username: process.env.STACKONE_API_KEY, password: "", }, }); app.post('/stackone_connect_sessions', async (req, res) => { const { originUsername, provider } = req.body; try { const result = await stackOne.connectSessions.createConnectSession({ originOwnerId: "customer-123", originOwnerName: "Acme Inc", originUsername: originUsername, provider, }); res.send({ token: result.connectSessionTokenAuthLink?.token }); } catch (e) { res.status(500).send('error when trying to fetch session'); } }); ``` ```python Python (HTTP) from flask import Flask, request, jsonify import requests import base64 app = Flask(__name__) @app.route('/stackone_connect_sessions', methods=['POST']) def stackone_connect_sessions(): STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY' headers = { 'Authorization': 'Basic ' + base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode(), 'Content-Type': 'application/json', } req_data = request.json payload = { 'origin_owner_id': 'customer-123', 'origin_owner_name': 'Acme Inc', 'origin_username': req_data.get('originUsername'), 'provider': req_data.get('provider'), } try: response = requests.post( 'https://api.stackone.com/connect_sessions', headers=headers, json=payload ) token = response.json().get('token') return jsonify({'token': token}) except Exception as e: return ('error when trying to fetch session', 500) ``` Return the token to your frontend, where the Hub consumes it to start [account linking](/embed/account-linking/overview). ## New or existing account The `origin_owner_id` + `origin_owner_name` + `provider` combination decides whether a new account is created or an existing one is updated: | Combination seen before? | Result | |---|---| | No | New account created | | Yes | Existing account opened in edit mode | | Yes, with `account_id` | That specific account opened in edit mode | | Yes, with `multiple: true` (no `account_id`) | New account created regardless of existing ones | Use `multiple: true` when one customer needs several separate accounts for the same provider. It has no effect when `account_id` is set. To list a customer's linked accounts later, filter `GET /accounts` by `origin_owner_id`. See [Multi-Tenant Accounts](/features/multi-tenant-accounts). ## Target a specific connector profile Passing `provider` alone uses the project's [default connector profile](/connect/managing-connectors/overview) for that provider, which is right for most cases. To route a session to a specific profile (multiple profiles per provider, or migrating users to a new connector version), pass its `connector_profile_id`. Get the ID from [`GET /v2/connector_profiles`](/platform/api-reference/v2/connector-profiles/list-connector-profiles): ```bash curl -X POST https://api.stackone.com/connect_sessions \ -H "Authorization: Basic " \ -H "Content-Type: application/json" \ -d '{ "origin_owner_id": "customer-123", "origin_owner_name": "Acme Inc", "provider": "bamboohr", "connector_profile_id": "01JHMM0V..." }' ``` The resulting account inherits that profile's connector version pin. The most common reason to target a profile this way is moving end users onto a new connector major version that requires them to reauthenticate. See [Migrating to a new version](/connector-building/connector-versioning#migrating-to-a-new-version) for that flow. ## Filtering connectors Control which connectors appear in the Hub by configuring the connect session on your backend. You can specify a `provider` or `categories` property when creating the connect session to control which connectors appear in the Hub: - **`provider`**: Opens the Hub directly at the credential entry screen for a specific connector, bypassing the connector listing - **`categories`**: Filters the Hub to show only connectors from specified categories (e.g., `hris`, `ats`) If neither is specified, the Hub displays all connectors enabled for the project. The connector specified in `provider` must have an enabled [connector profile](/connect/managing-connectors/overview) in the associated project. Retrieve valid `provider` keys from [`GET /v2/connectors`](/platform/api-reference/v2/connectors/list-connectors). Each connector in the response carries a `key`, which is the value to pass here. ```javascript JavaScript // Skip connector list, go directly to BambooHR const result = await stackOne.connectSessions.createConnectSession({ originOwnerId: "customer-123", originOwnerName: "Acme Inc", provider: "bamboohr", // Go directly to this connector }); ``` ```javascript JavaScript (Categories) // Show only HRIS connectors const result = await stackOne.connectSessions.createConnectSession({ originOwnerId: "customer-123", originOwnerName: "Acme Inc", categories: ["hris"], // Filter to HRIS category }); ``` ## Next steps Embed the Hub, or share an Auth Link, to consume the token you just created. React to accounts being linked, updated, or disconnected. Keep each customer's linked accounts separate with `origin_owner_id`. Every request field and response shape. # Account Linking - StackOne Hub Source: https://docs.stackone.com/embed/account-linking/overview Let end-users authenticate and connect their accounts to your system The **StackOne Hub** allows your end-users to authenticate and connect their accounts into your application or agent. The Hub can either be embedded in your code, or for a no-code approach, you can generate a StackOne hosted web link you share with them that has the Hub pre-embedded. ## How it works 1. Your backend creates a [connect session](/embed/connect-session) and returns its **session token** to your frontend. 2. Display the **Hub** (or share an [Auth Link](/embed/account-linking/auth-link)) with that token. The end-user selects a connector and authenticates. 3. On a successful link, the **account ID** is returned via callback, event, or the `account.created` [webhook](/connect/webhooks). 4. Use that account ID to [call actions](/embed/call-actions/overview) on the account from your product.

## Embed it or share a link The Hub reaches your end-users two ways. Embed it in your product for a branded in-app flow, or share an [Auth Link](/embed/account-linking/auth-link), a StackOne-hosted page with the Hub already embedded, generated from the dashboard or programmatically. You can also link an account directly from the dashboard, for internal tools or on a customer's behalf. See [Linking Accounts](/connect/managing-connectors/linking-accounts#link-from-the-dashboard). | | Embedded Hub | Auth Link | |---|---|---| | Where it runs | In your app | StackOne-hosted page | | Frontend work | Install and mount the Hub | None: share a URL | | Branding | Themed to match your app | StackOne-hosted | | Knowing it worked | Callbacks or webhooks | Webhooks only | | Best for | Production apps | Email flows, sales-led onboarding, demos | ## Ways to embed The StackOne Hub as a native React component (`@stackone/hub`). The same Hub as a framework-agnostic custom element (``) for non-React apps. A StackOne hosted web page showing the Hub that can be shared directly with end-users. Using the Legacy Hub? `@stackone/react-hub` remains available for existing implementations, but the Hub is required to fully support new features. Its setup and hook API are documented on [npm](https://www.npmjs.com/package/@stackone/react-hub). ## Next steps With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP. Return to the end-to-end embedding journey. # StackOne Hub (React) Source: https://docs.stackone.com/embed/account-linking/stackone-hub Embed the native React `` component to let end-users connect their accounts The **StackOne Hub** (`@stackone/hub`) is a native React `` component that renders directly in your React tree. It offers filtering, search, detailed error messages, and full theming support. It is the **recommended** way to implement the Hub. ## Quick start ```bash npm npm install @stackone/hub ``` ```bash yarn yarn add @stackone/hub ``` ```bash pnpm pnpm add @stackone/hub ``` The Hub needs a [connect session token](/embed/connect-session) to securely communicate with StackOne. This token must be generated server-side to keep your API key secure. ```typescript async function retrieveConnectSessionToken() { const response = await fetch('/api/stackone/connect-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'jane@example.com' }), }); const { token } = await response.json(); return token; } ``` To route the session through a specific **connector profile** (when a provider has more than one), pass its `connector_profile_id` when creating the session. See [Target a specific connector profile](/embed/connect-session#target-a-specific-connector-profile). ```tsx import { StackOneHub } from "@stackone/hub"; import { useEffect, useState } from "react"; function ConnectorPage() { const [token, setToken] = useState(); useEffect(() => { retrieveConnectSessionToken().then(setToken); }, []); if (!token) return

; return ( { console.log('Connected:', account.id, account.provider); }} onCancel={() => console.log('Cancelled')} onClose={() => console.log('Closed')} /> ); } ``` Your end-users now use the Hub to connect their accounts. Each successful link fires `onSuccess` with the linked account id — persist against your user — it's the account ID you'll use with every [action call](/embed/call-actions/overview). You can also capture it server-side from the `account.created` [webhook event](/embed/handle-account-events). ## Properties The `StackOneHub` component accepts these properties: | Property | Type | Default | Description | |------|------|---------|-------------| | `token` | `string` | — | Connect session token from your backend | | `mode` | `'integration-picker'` | `'integration-picker'` | Hub mode | | `accountId` | `string` | — | Pre-select a specific account to edit | | `baseUrl` | `string` | `'https://api.stackone.com'` | StackOne API base URL | | `appUrl` | `string` | `'https://app.stackone.com'` | StackOne App URL | | `height` | `string` | `'500px'` | Component height | | `theme` | `'light' \| 'dark' \| PartialMalachiteTheme` | `'light'` | Theme configuration | | `showFooterLinks` | `boolean` | `true` | Show footer links | | `onSuccess` | `(account: { id: string; provider: string }) => void` | — | Called when account is connected | | `onCancel` | `() => void` | — | Called when user cancels | | `onClose` | `() => void` | — | Called when hub closes | | `onCloseLabel` | `string` | `'Close'` | Custom label for the close button on the success screen | ```tsx import { StackOneHub } from "@stackone/hub"; { console.log(`Connected ${account.provider} with ID ${account.id}`); }} onCancel={() => console.log('User cancelled')} onClose={() => console.log('Hub closed')} onCloseLabel="Done" /> ``` Use `onSuccess` to update your UI or trigger backend syncs. Use `onClose` as a cleanup handler that always runs. ## Theming The Hub supports full theming with the `theme` property: ```tsx ``` For custom theming, pass a `PartialMalachiteTheme` object: ```tsx ``` See the [@stackone/hub repository](https://github.com/StackOneHQ/hub) for full theme options. For non-React stacks, use the [web components](/embed/account-linking/stackone-hub-web-component) build (``). For the older hook API, see [@stackone/react-hub](https://www.npmjs.com/package/@stackone/react-hub) on npm. ## Next steps With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP. Return to the end-to-end embedding journey. # StackOne Hub Web Component Source: https://docs.stackone.com/embed/account-linking/stackone-hub-web-component Embed StackOne Hub in any framework using the framework-agnostic custom element `@stackone/hub` ships a framework-agnostic custom element, ``, that you can drop into any HTML page or framework template. React and ReactDOM are bundled into the web-component build, so consumers don't need React installed. Use the web component for any non-React stack, or when you want a single code path across multiple frameworks. For a native React app, the [StackOne Hub (Native)](/embed/account-linking/stackone-hub) is usually a better fit. It integrates with your React tree and lets you pass callbacks as props. ## Quick start Install the package and register ``. The import is side-effecting. It registers `` on `customElements`. Point a ` ``` If you'd rather install via npm and bundle the script yourself, use the `import '@stackone/hub/webcomponent'` pattern shown in the other tabs. If you're starting fresh in React, the [`` component](/embed/account-linking/stackone-hub) is usually a better fit. It integrates with your React tree and lets you pass callbacks as props. Reach for the web component when you can't add another copy of React to your bundle, or when you want the same code path as your non-React surfaces. Install the package: ```bash npm npm install @stackone/hub ``` ```bash yarn yarn add @stackone/hub ``` ```bash pnpm pnpm add @stackone/hub ``` Register the element at app entry: ```tsx // src/main.tsx import '@stackone/hub/webcomponent'; import { StrictMode } from 'react'; import { createRoot } from 'react-dom/client'; import App from './App'; const root = document.getElementById('root'); if (!root) { throw new Error('#root element not found'); } createRoot(root).render( , ); ``` Tell TypeScript that `` is a valid JSX tag: ```tsx declare global { // biome-ignore lint/style/noNamespace: JSX intrinsic-element augmentation requires namespace syntax. namespace JSX { interface IntrinsicElements { 'stackone-hub': React.DetailedHTMLProps< React.HTMLAttributes & { token?: string; mode?: string; 'base-url'?: string; 'app-url'?: string; 'account-id'?: string; height?: string; theme?: string; 'show-footer-links'?: boolean | string; 'on-close-label'?: string; }, HTMLElement >; } } } ``` Install the package: ```bash npm npm install @stackone/hub ``` ```bash yarn yarn add @stackone/hub ``` ```bash pnpm pnpm add @stackone/hub ``` Vue's template compiler treats unknown tags as Vue components by default. Mark `stackone-hub` as a custom element so it falls through to the DOM: ```ts // vite.config.ts import vue from '@vitejs/plugin-vue'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === 'stackone-hub', }, }, }), ], }); ``` Register the element at app entry: ```ts // src/main.ts import '@stackone/hub/webcomponent'; import { createApp } from 'vue'; import App from './App.vue'; createApp(App).mount('#app'); ``` Svelte treats unknown tags as custom elements automatically. No extra config required. Install the package: ```bash npm npm install @stackone/hub ``` ```bash yarn yarn add @stackone/hub ``` ```bash pnpm pnpm add @stackone/hub ``` Register the element at app entry: ```ts // src/main.ts import '@stackone/hub/webcomponent'; import { mount } from 'svelte'; import App from './App.svelte'; const target = document.getElementById('app'); if (!target) { throw new Error('#app element not found'); } mount(App, { target }); ``` Install the package: ```bash npm npm install @stackone/hub ``` ```bash yarn yarn add @stackone/hub ``` ```bash pnpm pnpm add @stackone/hub ``` Add `CUSTOM_ELEMENTS_SCHEMA` to the component (or module) that uses `` so Angular accepts unknown tags as custom elements: ```ts // src/app/app.component.ts import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core'; @Component({ selector: 'app-root', standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA], templateUrl: './app.component.html', }) export class AppComponent {} ``` Register the element at app entry: ```ts // src/main.ts import '@stackone/hub/webcomponent'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app/app.component'; bootstrapApplication(AppComponent).catch((err) => console.error(err)); ``` The Hub needs a [connect session token](/embed/connect-session) to communicate with StackOne. Generate it server-side to keep your API key off the client. ```typescript async function retrieveConnectSessionToken() { const response = await fetch('/api/stackone/connect-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'jane@example.com' }), }); const { token } = await response.json(); return token; } ``` To route the session through a specific **connector profile** (when a provider has more than one), pass its `connector_profile_id` when creating the session. See [Target a specific connector profile](/embed/connect-session#target-a-specific-connector-profile). Mount the element, set the token, and listen for events: ```html ``` React 19 passes unknown props through as attributes, but events still need to be wired with `addEventListener` via a `ref`. React's `onSuccess={...}` JSX shorthand does **not** fire on native DOM `CustomEvent`s. ```tsx import { useEffect, useRef, useState } from 'react'; export default function App() { const [token, setToken] = useState(''); const hubRef = useRef(null); useEffect(() => { retrieveConnectSessionToken().then(setToken); }, []); useEffect(() => { const el = hubRef.current; if (!el) return; const onSuccess = (event: Event) => { const detail = (event as CustomEvent).detail; console.log('Connected:', detail.id, detail.provider); }; const onClose = () => console.log('Closed'); el.addEventListener('success', onSuccess); el.addEventListener('close', onClose); return () => { el.removeEventListener('success', onSuccess); el.removeEventListener('close', onClose); }; }, []); return ( ); } ``` Vue passes `:prop="value"` bindings through as HTML attributes when the tag is registered as a custom element. Vue's `@event` shorthand does **not** fire on native DOM `CustomEvent`s. Subscribe with `addEventListener` via a `ref` instead. ```vue ``` Svelte passes attribute bindings through directly. Its `on:event` shorthand **does** fire on native DOM `CustomEvent`s, so `` works. The example below uses `addEventListener` via `bind:this` to keep the typing explicit. ```svelte ``` Bind attributes with `[attr.name]="value"` to keep them as attributes rather than Angular property bindings. Angular's `(event)` template binding **does** fire on native DOM `CustomEvent`s, so `(success)="onSuccess($event)"` works. The example below uses `addEventListener` via `@ViewChild` for explicit teardown in `ngOnDestroy`. ```ts // src/app/app.component.ts import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, OnDestroy, ViewChild, } from '@angular/core'; @Component({ selector: 'app-root', standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` `, }) export class AppComponent implements AfterViewInit, OnDestroy { @ViewChild('hub') hubRef?: ElementRef; token = ''; private onSuccess = (event: Event) => { const detail = (event as CustomEvent).detail; console.log('Connected:', detail.id, detail.provider); }; private onClose = () => console.log('Closed'); async ngAfterViewInit() { this.token = await retrieveConnectSessionToken(); this.hubRef?.nativeElement.addEventListener('success', this.onSuccess); this.hubRef?.nativeElement.addEventListener('close', this.onClose); } ngOnDestroy() { this.hubRef?.nativeElement.removeEventListener('success', this.onSuccess); this.hubRef?.nativeElement.removeEventListener('close', this.onClose); } } ``` Your end-users now use the Hub to connect their accounts. Each successful link fires the `success` event with the linked account id — persist against your user — it's the account ID you'll use with every [action call](/embed/call-actions/overview). You can also capture it server-side from the `account.created` [webhook event](/embed/handle-account-events). ## Attributes The `` element accepts these attributes. All scalar `StackOneHub` properties map to kebab-case HTML attributes: | Attribute | Type | Default | Description | |---|---|---|---| | `token` | string | — | Connect session token from your backend | | `mode` | `integration-picker` | `integration-picker` | Hub mode | | `base-url` | string | `https://api.stackone.com` | StackOne API base URL | | `app-url` | string | `https://app.stackone.com` | StackOne App URL | | `height` | string | `500px` | Component height | | `theme` | `light` \| `dark` \| JSON object | `light` | Theme keyword or a JSON-encoded `PartialMalachiteTheme` | | `account-id` | string | — | Pre-select a specific account to edit | | `on-close-label` | string | `Close` | Custom label for the close button | | `show-footer-links` | boolean attribute | `true` | Toggle footer visibility | ## Style Customization Set the `theme` attribute to `light` or `dark`: ```html ``` For custom theming, pass a `PartialMalachiteTheme`. Because HTML attributes are strings, use `JSON.stringify(...)` to encode the object first. The `theme` attribute receives a JSON-encoded `PartialMalachiteTheme` string, not an object: ```html ``` Bind the `theme` attribute like any other with `[attr.theme]`, using a component property that holds a JSON-encoded `PartialMalachiteTheme`, the string produced by `JSON.stringify(...)`, since attributes are strings, not objects: ```ts @Component({ selector: 'app-root', standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` `, }) export class AppComponent { themeJson = JSON.stringify({ colors: { primary: { background: '#6366f1', foreground: '#ffffff', }, card: { background: '#fafafa', }, }, }); } ``` For a keyword theme, bind a plain string (`themeJson = 'dark'`) or set the attribute directly (`theme="dark"`). See the [@stackone/hub repository](https://github.com/StackOneHQ/hub) for full theme options. ## Events Callbacks are dispatched as native DOM `CustomEvent`s on the host element with `bubbles: true` and `composed: true`. | Event | `event.detail` | |---|---| | `success` | `{ id: string; provider: string }` | | `close` | `undefined` | Framework-emitted event shorthands behave differently from native DOM `CustomEvent`s. React's `onSuccess={...}` and Vue's `@event` do **not** fire on them. Subscribe with `addEventListener` via a ref. Svelte's `on:event` and Angular's `(event)` **do** fire on them. ## Next steps With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP. Return to the end-to-end embedding journey. # Hub (Auth Link) Source: https://docs.stackone.com/embed/account-linking/auth-link Get end-users to connect their accounts with only a link! Hub **Auth Links** let you deliver a secure URL to your end users for a secure, in-browser connection experience **without** embedding the StackOne Hub in your application. The hosted webpage already includes an implementation of the Hub so there's no front end implementation required from your side. ## Generating a link You can generate an Auth Link from the dashboard or programmatically via the API. An Auth Link can be generated directly from the StackOne dashboard. Here's how: Log in to the StackOne dashboard and select [Accounts](https://app.stackone.com/accounts) from the left menu. A popup will appear asking you to select a method. Choose **Method 1 - Request Authentication**. ![Accounts page with Link Account button](/images/accounts-page-link-account.png) * **Origin owner ID** - This should be the end-user identifier you use in your own system(s) (most likely, a UUID or integer) * **Origin owner name** - This is the end-user name in your own system(s) * **Origin username** (optional) - The end-user's username (eg: an email address) that will connect or be responsible for the connection Then click **Next**. ![Auth Link form](/images/auth-link-form.png) * **Filter the Hub** - Filter the list of connectors displayed to the end-user * **Connector Profile** - Route the session through a specific connector profile * **Link Expiry** - Control how long the link stays valid (default is 30 days) Then click **Generate**. ![Auth Link generated](/images/auth-link-generated.png) The end-user will now be able to connect their accounts using the link. Once the end-user connects, StackOne fires an `account.created` [webhook event](/embed/handle-account-events) containing the account ID. Persist it against your user: it's the account ID you'll use with every [action call](/embed/call-actions/overview). You can also find it through the dashboard on the [Accounts](https://app.stackone.com/accounts) page.

To support a more scalable solution, you can programmatically generate links for end-users. Call the [Create Connect Session](/platform/api-reference/connect-sessions/create-connect-session) endpoint with the end-user's details: * `origin_owner_id` - The end-user identifier in your own system(s), which is how accounts map to your customers in a [multi-tenant setup](/features/multi-tenant-accounts) * `origin_owner_name` - The end-user name in your own system(s) * `origin_username` (optional) - The end-user's username, e.g. an email address * `categories` (optional) - Filter the list of connectors displayed to the end-user * `expires_in` (optional) - How long the link stays valid, in seconds * `connector_profile_id` (optional) - Route the session through a specific [connector profile](/embed/connect-session#target-a-specific-connector-profile) The response contains an `auth_link_url` property. This is the link to send to the end-user. Deliver the `auth_link_url` to your end-user (for example by email). When they open it, they'll see the **StackOne Hub** listing the connectors enabled on your project, where they select and connect their account. ![StackOne Hub Connector Listing](/images/hub-connector-listing.png) Once the end-user connects, StackOne fires an `account.created` [webhook event](/embed/handle-account-events) containing the account ID. Persist it against your user: it's the account ID you'll use with every [action call](/embed/call-actions/overview). You can also find it through the dashboard on the [Accounts](https://app.stackone.com/accounts) page, or via the [List Accounts endpoint](/platform/api-reference/v2/accounts/list-accounts). Set `expires_in` (in seconds) to give end-users enough time to complete the connection. (eg. 5 days is 432000, 7 days is 604800) ## Next steps With the account linked, call its actions from your product over the Agent SDK, MCP, A2A, or RPC/HTTP. Return to the end-to-end embedding journey. # Handle Account Events Source: https://docs.stackone.com/embed/handle-account-events Subscribe to and handle StackOne's account lifecycle webhooks in your backend. Account events let your backend react to account lifecycle — a user connecting or disconnecting — instead of polling. This is the implementation walkthrough; for the event catalog and payload fields, see [Platform Events](/platform-api/platform-events) in the reference. Expose an HTTPS endpoint in your backend that returns `200` quickly. On the [Webhooks](https://app.stackone.com/webhooks) page, click **Add Webhook** and register its URL. From the **Signing secrets** tab, copy the signing secret if you plan to verify signatures (recommended). Account events are subscribed **on the webhook itself**, not on a connector profile (that's for connector events). When you add or edit the webhook on the [Webhooks](https://app.stackone.com/webhooks) page, select the account events you want: `account.created`, `account.updated`, and `account.deleted`. Via the API, set the webhook's `events` array when you create it (`POST /webhooks`) or update it (`PATCH /webhooks/{id}`): ```json { "webhook_url": "https://your-app.com/webhooks/stackone", "label": "account-lifecycle", "events": ["account.created", "account.updated", "account.deleted"] } ``` Each delivery is signed with HMAC-SHA256 over the raw request body, base64url-encoded, in the `x-stackone-signature` header. Verify it against your signing secret before trusting the payload: ```javascript import { createHmac, timingSafeEqual } from 'crypto'; function isSignatureValid(signature, rawBody, signingSecret) { if (!signature) return false; const expected = createHmac('sha256', signingSecret) .update(rawBody) .digest('base64url'); const a = Buffer.from(expected); const b = Buffer.from(signature); return a.length === b.length && timingSafeEqual(a, b); } ``` Hash the **raw request bytes** (not a re-serialized JSON string), and compare in constant time. See [Verifying webhook signatures](/connect/webhooks#verifying-webhook-signatures) for detail and secret rotation. Switch on the `event` field and act on the account. The payload carries `account_id`, `provider`, and the `origin_*` identifiers. See the [payload reference](/platform-api/platform-events#payload). ```javascript import express from 'express'; const app = express(); app.post('/webhooks/stackone', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-stackone-signature']; if (!isSignatureValid(signature, req.body, process.env.STACKONE_SIGNING_SECRET)) { return res.status(401).send('invalid signature'); } const { event, account_id, provider } = JSON.parse(req.body); switch (event) { case 'account.created': // kick off an initial sync for the new account break; case 'account.updated': // re-check scopes or resume a paused sync break; case 'account.deleted': // revoke downstream access and clean up the stored account_id break; } res.sendStatus(200); }); ``` [Auth Links](/embed/account-linking/auth-link) have no frontend callback, so `account.created` is how you know an account was linked. # Call Actions Source: https://docs.stackone.com/embed/call-actions/overview Choose how to invoke StackOne actions: direct API, MCP, A2A, or SDKs Once an account is linked, you can call its actions from your product. For the full journey up to that point — API key, connector profile, account linking — see the [Embed overview](/embed/getting-started). **Actions** are the atomic operations in StackOne: `salesforce_list_contacts`, `gmail_send_message`, `google_drive_list_files`, etc. Every protocol is just a different way to invoke the same underlying actions. All protocols route through the **same engine**, so authentication, rate limiting, data transformation, and error recovery are handled for every action. The choice comes down to your use case and how you're building. ## Protocols **Native TypeScript/Python** with framework integrations (LangChain, CrewAI, OpenAI) **Open standard** for AI tools. Works with Claude, Cursor, Vercel AI, n8n Call a pre-built agent per integration, for multi-agent orchestration. Call an action from any backend or script with no agent or framework. ## Which protocol? | | [Agent SDK](/embed/call-actions/agent-sdk) | [MCP](/embed/call-actions/mcp) | [A2A](/embed/call-actions/agent2agent) | [RPC/HTTP](/embed/call-actions/rpc-http) | |---|-----------|-----|-----|----------| | **Use case** | AI agents with frameworks | MCP-compatible clients | Multi-agent systems | Traditional apps, scripts | | **Best for** | Programmatic control: load, filter, and select tools dynamically | Quick setup, IDE agents, switching accounts by header | Agent orchestration, context isolation, long-running async tasks | Full control, non-agentic | | **Skip it when** | You just want tools in an existing MCP client | You need programmatic control or custom error handling | You need synchronous responses in a single agent | You're building an AI agent | | **Requires code** | Yes | No (config only) | Yes | Yes | | **Works with** | Any AI framework (LangChain, CrewAI, Vercel AI SDK, …) | Any MCP client (Claude, Cursor, Windsurf, n8n, …) | Any A2A orchestrator | Any HTTP client | ## Mixing protocols Many production setups combine protocols. They all use the same actions and authentication, so you can mix and match: - **RPC/HTTP for backend jobs** (scheduled syncs, data pipelines) - **Agent SDK for your product** (customer-facing AI features) - **MCP for internal tools** (Cursor, Claude Desktop for your team) - **A2A for complex workflows** (multi-agent orchestration) Exposing hundreds of actions? Use [Tool Discovery](/features/tool-discovery) so the agent searches at runtime instead of overloading its context window. It works through both MCP (`search_execute` mode) and the SDK (tool search). # Agent SDK Source: https://docs.stackone.com/embed/call-actions/agent-sdk Install, fetch, filter, and execute typed StackOne tools in TypeScript and Python agent frameworks. Bring StackOne actions into your code as typed TypeScript and Python tools. Fetch the tools for a [linked account](/gateway/concepts/linked-accounts), filter them to what your agent needs, and hand them to your framework's function-calling loop. The SDK is available in two languages: | | TypeScript | Python | |---|------------|--------| | Package | [`@stackone/ai`](https://www.npmjs.com/package/@stackone/ai) (npm) | [`stackone-ai`](https://pypi.org/project/stackone-ai/) (pip) | | Frameworks | [OpenAI Functions](/embed/call-actions/agent-sdk/openai), [Vercel AI SDK](/embed/call-actions/agent-sdk/vercel-ai-sdk) | [LangChain](/embed/call-actions/agent-sdk/langchain), [CrewAI](/embed/call-actions/agent-sdk/crewai), [OpenAI](/embed/call-actions/agent-sdk/openai), [LangGraph](/embed/call-actions/agent-sdk/langgraph), [Pydantic AI](/embed/call-actions/agent-sdk/pydantic-ai) | **Not sure if the Agent SDK is right for you?** Check out [Call Actions](/embed/call-actions/overview) to understand when to use the Agent SDK vs MCP vs A2A. StackOne Architecture

Your agent connects to StackOne, which handles authentication and data normalization for hundreds of [SaaS providers](/connectors/introduction) like Salesforce, Workday, Slack, and more. | Component | Description | |-----------|-------------| | **Your Agent** | Built with LangChain, CrewAI, OpenAI, Vercel AI, or any framework | | **StackOne** | AI Integration Gateway: handles authentication, transforms data, manages connections | | **SaaS Providers** | Salesforce, Workday, Greenhouse, Slack, Gmail, HubSpot, and hundreds more | Key concepts: - **Initialize a ToolSet**: Create a `StackOneToolSet` instance to access tools for providers like Workday, Greenhouse, Slack, and more - **Filter Tools**: Use provider glob patterns like `workday_*` and `slack_*`, or the `fetch_tools()` method for provider/action/account filters - **Execute Tools**: Call provider APIs through StackOne tool interfaces: list employees, send messages, create tickets - **[Tool Discovery](/features/tool-discovery)**: Discover relevant tools at runtime via natural language queries - **Multi-Tenant**: Each tool execution requires an `account_id` to identify which customer's [account](/gateway/concepts/linked-accounts) to access ## Calling actions Before starting you need to have followed the previous setup steps described in the [Getting Started](/embed/getting-started). Then pick your framework. Each guide is a complete agent loop, from install to handing StackOne tools to your model: TypeScript and Python TypeScript Python Python Python Python ## Resources - **[GitHub (TypeScript)](https://github.com/StackOneHQ/stackone-ai-node)** and **[GitHub (Python)](https://github.com/StackOneHQ/stackone-ai-python)**: Complete source code and examples - **[Examples (TypeScript)](https://github.com/StackOneHQ/stackone-ai-node/tree/main/examples)**: OpenAI integration, semantic search, and file uploads - **[Examples (Python)](https://github.com/StackOneHQ/stackone-ai-python/tree/main/examples)**: LangChain, CrewAI, and semantic search examples - **[NPM Package](https://www.npmjs.com/package/@stackone/ai)** and **[PyPI Package](https://pypi.org/project/stackone-ai/)**: Package details and version history # OpenAI Source: https://docs.stackone.com/embed/call-actions/agent-sdk/openai Build AI agents with OpenAI function calling using the StackOne Agent SDK for TypeScript or Python StackOne tools work with OpenAI's function calling to build AI agents that access business data. **Supported languages:** TypeScript and Python. - **Convert tools** to OpenAI function schemas automatically - **Execute functions** with built-in handling - **Build conversational agents** with tool execution - **Multi-step workflows** for complex tasks ## Calling actions ```bash TypeScript # Requires Node.js 16.0 or higher # TypeScript 4.5 or higher (recommended) # Using npm npm install @stackone/ai openai # Using pnpm pnpm add @stackone/ai openai # Using yarn yarn add @stackone/ai openai # Using bun bun add @stackone/ai openai export STACKONE_API_KEY=your_api_key_here ``` ```bash Python # Requires Python 3.10 or higher # Using uv (recommended) uv add 'stackone-ai[mcp]' openai # Using pip pip install 'stackone-ai[mcp]' openai # Optional: install with example dependencies uv add 'stackone-ai[mcp,examples]' pip install 'stackone-ai[mcp,examples]' export STACKONE_API_KEY=your_api_key_here ``` Two approaches to retrieving tools: 1. [Fetch Tools (with filtering)](/features/tool-discovery#tool-filtering): fetch all tools upfront with optional filters applied. 2. [Advanced Tool Search](/features/tool-discovery#advanced-tool-search): hand the model just `tool_search` + `tool_execute` and let the agent discover what it needs at runtime. See [Tool Discovery](/features/tool-discovery) for more details on which may be best in your scenario. By default this fetches every tool enabled for the account. Narrow it by passing `providers` (specific connectors) or `actions`, exact names or glob patterns, following the `provider_operation_entity` tool naming (e.g. `workday_*`, or `*_list_*` for read-only tools). ```typescript TypeScript import OpenAI from 'openai'; import { StackOneToolSet } from '@stackone/ai'; // Get account ID from your app's auth context or StackOne dashboard const accountId = 'your-account-id'; const openai = new OpenAI(); const toolset = new StackOneToolSet(); // Fetch tools dynamically for this account. // Optionally narrow the fetch with filters: // providers: ["hibob", "workday"] — only these connectors // actions: ["*_list_*", "*_get_*"] — glob patterns, e.g. read-only actions const tools = await toolset.fetchTools({ accountIds: [accountId] }); // Convert to OpenAI function format const openAITools = tools.toOpenAI(); ``` ```python Python from openai import OpenAI from stackone_ai import StackOneToolSet # Initialise clients client = OpenAI() toolset = StackOneToolSet() # Fetch StackOne tools. # Optionally narrow the fetch with filters: # providers=["hibob", "workday"] — only these connectors # actions=["*_list_*", "*_get_*"] — glob patterns, e.g. read-only actions tools = toolset.fetch_tools( actions=['workday_get_worker', 'workday_list_workers'], account_ids=['your-account-id'] ) # Convert to OpenAI function format openai_tools = tools.to_openai() ``` The LLM receives only 2 tools and searches the catalog autonomously: ```typescript TypeScript import { StackOneToolSet } from '@stackone/ai'; const toolset = new StackOneToolSet({ search: { method: 'semantic', topK: 3 }, }); // tools contains only tool_search + tool_execute const tools = toolset.getTools({ accountIds: ['your-account-id'] }); // Convert to OpenAI function format — the agent loop also uses // `tools` to execute the calls the model makes const openAITools = tools.toOpenAI(); ``` ```python Python from stackone_ai import StackOneToolSet toolset = StackOneToolSet( search={"method": "semantic", "top_k": 3}, execute={"account_ids": ["your-account-id"]}, ) # LLM receives only 2 tools - it searches and executes autonomously. # .openai() returns OpenAI-format tools directly, so no conversion is needed openai_tools = toolset.openai(mode="search_and_execute") ``` Create the completion with the tools attached, then execute any tool calls the model makes: ```typescript TypeScript // Create completion with function calling const completion = await openai.chat.completions.create({ model: 'gpt-5.4', messages: [ { role: 'system', content: 'You are an HR assistant with access to employee data.' }, { role: 'user', content: 'How many employees do we have?' } ], tools: openAITools, tool_choice: 'auto' }); // Execute any tool calls const message = completion.choices[0].message; if (message.tool_calls) { for (const toolCall of message.tool_calls) { const tool = tools.getTool(toolCall.function.name); if (tool) { const result = await tool.execute( JSON.parse(toolCall.function.arguments) ); console.log('Result:', result.data); } } } ``` ```python Python # Create an AI agent with tool access response = client.chat.completions.create( model="gpt-5.4", messages=[ { "role": "system", "content": "You are an HR assistant with access to employee data." }, { "role": "user", "content": "How many employees are in engineering?" } ], tools=openai_tools, tool_choice="auto" ) # Handle tool calls message = response.choices[0].message if message.tool_calls: for tool_call in message.tool_calls: tool = tools.get_tool(tool_call.function.name) if tool: result = tool.execute(tool_call.function.arguments) print(f"Result: {result}") ``` The model first calls `tool_search`, then `tool_execute`. The same loop as the Fetch tools tab, run until the model stops calling tools: ```typescript TypeScript // Route every tool call through the toolset and feed the result // back until the model stops import OpenAI from 'openai'; const client = new OpenAI(); const messages: OpenAI.ChatCompletionMessageParam[] = [ { role: 'system', content: 'Use tool_search to find relevant tools, then tool_execute to run them. ' + 'Read parameter schemas from tool_search results carefully.', }, { role: 'user', content: 'List my upcoming Calendly events for the next week.' }, ]; for (let step = 0; step < 10; step++) { const response = await client.chat.completions.create({ model: 'gpt-5.4', messages, tools: openAITools, tool_choice: 'auto', }); const choice = response.choices[0]; if (!choice.message.tool_calls?.length) { console.log(choice.message.content); break; } messages.push(choice.message); for (const toolCall of choice.message.tool_calls) { // Look the meta tool up in the collection from the fetch step const tool = tools.getTool(toolCall.function.name); const result = tool ? await tool.execute(toolCall.function.arguments) : { error: `Tool "${toolCall.function.name}" not found` }; messages.push({ role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(result), }); } } ``` ```python Python # Route every tool call through the toolset and feed the result # back until the model stops import json from openai import OpenAI client = OpenAI() messages = [ { "role": "system", "content": ( "Use tool_search to find relevant tools, then tool_execute to run them. " "Read parameter schemas from tool_search results carefully." ), }, {"role": "user", "content": "List my upcoming Calendly events for the next week."}, ] for _step in range(10): response = client.chat.completions.create( model="gpt-5.4", messages=messages, tools=openai_tools, tool_choice="auto", ) choice = response.choices[0] if not choice.message.tool_calls: print(choice.message.content) break messages.append(choice.message.model_dump(exclude_none=True)) for tool_call in choice.message.tool_calls: result = toolset.execute(tool_call.function.name, tool_call.function.arguments) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result), }) ``` ## Example A full runnable example: