Custom integrations

Connect Siit to any HTTPS API without a built-in connector, then declare the actions Siit can run on it from requests, workflows and app access roles

---

A custom integration connects Siit to a tool that has an HTTPS API but no built-in Siit connector: an internal service, a niche SaaS or a homegrown tool. You set it up once with its credentials, then declare custom actions, the operations Siit can run on that API, such as Create a VPN account, Reset a badge or Open a purchase order.

Actions are configured with URLs and input definitions, without code. Siit calls the API at the moment an action runs. Custom integrations don't sync any data in the background.

Where custom actions run

Where	How
On a request or a person	An admin runs the action by hand from the request side panel or the person's About menu
In a workflow	As a workflow step, with inputs filled from workflow variables. Outputs become variables for later steps and branch conditions
In an app access role	As a provisioning or deprovisioning step, for apps that have no native connector
With Assist	As a tool Assist can use, when integration actions are enabled for Assist in your workspace

Every run is recorded with its inputs, the response and its status. Successful runs also appear on the request or person timeline.

Before you start

• Custom integrations depend on your plan. If you don't see the Custom category in the Integration library, contact us through in-app chat.

• Creating and editing them requires the Can configure integrations permission.

• From the third party's API documentation, gather:

  • the credentials: an API token, an API key and the header it goes in, or a username and password

  • the URL and HTTP method of each endpoint you want to call

  • the response format, if you want to reuse a value from it (a created ID, a status) in later workflow steps

All URLs must use https:// and point to a public address. Siit refuses http:// URLs, private or internal IP addresses, and redirects.

Create a custom integration

Open the Custom category

Go to Settings → Workspace → Integration library and open the Custom category. It lists one card per custom integration, next to a Create a custom integration card.

Describe the integration

• Name (required): usually the name of the tool. It must be unique among your custom integrations.

• Logo (optional): shown on cards, workflow steps and menus.

• API documentation URL (optional): a link for the next admin who maintains the integration.

Choose an authentication method

Method	What Siit sends on every call	Fields
Bearer token	Authorization: Bearer <token>	Bearer token
API key header	The key in a header you name, for example X-API-Key: <key>	Header name, API key
Basic auth	Authorization: Basic <base64(username:password)>	Username (no colon), Password

The secret is encrypted and write-only: nobody can view it again, admins included. When you edit the integration, leave the field blank to keep the stored value, or type a new one to replace it.

Save

Custom headers and custom actions become available after the first save, because the variables they can use are only known once the integration exists.

Custom headers

Add custom headers when the API needs more than the authentication header, for example a tenant ID, an API version or a second credential.

• Up to 20 headers per integration, sent on every call of every action.

• Names and values accept company variables, custom variables and secrets, such as {{secrets.my_api_secret}}. See Variables & Secrets.

• Siit sets Accept and Content-Type itself. If a custom header has the same name as the authentication header, the authentication header is used.

Insert variables with the Insert a variable button or the {{ autocomplete. A variable typed by hand, like {{company.name}}, stays plain text and reaches the third party as written.

Declare a custom action

Open the integration and click New action. The Custom actions table lists each action with its context, status, manual run mode, the workflows that use it and its last update.

Name and status

• Name (required): what admins see in menus. It must be unique within the integration.

• Description (optional): shown to admins when they pick the action.

• Enabled: new actions are created disabled, so nothing can run them until you turn this on.

Context

The context is what the action runs on. It decides where the action is offered and which variables it can use.

Context	Runs on	Offered on
Request	A request	Request pages and request workflows
Person	A person	People and request pages, request and people workflows
No target	Nothing in particular	Request and people pages, and every workflow
App access request	An app access request	App access workflows and app access role provisioning steps. Never run by hand

HTTP request

• HTTP method: GET, POST, PUT or DELETE. New actions default to POST.

• Submit URL (required): the HTTPS endpoint Siit calls when the action runs.

With POST, PUT and DELETE, Siit sends the input values as a JSON object keyed by input slug:

{ "email": "[e-mail]", "department": "sales", "notify": true }

{% hint style="info" %} A GET request has no body, so a GET action can't declare inputs. Use another method if the API needs values from Siit. {% endhint %}

Manual runs

This setting controls whether an admin can run the action by hand from a request or a person, and what they fill in.

Mode	Behavior
Not offered (default)	The action can't be run by hand. It can still be used in workflows and app access roles
Without inputs	The admin confirms and the action runs
With the inputs below	The admin fills in a form built from the inputs you declare here. These are separate from the workflow inputs
With inputs fetched from a URL	Each time an admin opens the action, Siit calls the Input definition URL with GET to build the form. The third-party tool decides what to ask, for example a list of valid projects

Offer to workflows

Turn on Offer to workflows to make the action available in workflows and app access roles, then declare the inputs they must fill in. Leave the list empty for an action that takes no input. In a workflow, text inputs accept workflow variables, such as the requester's email or a field from the request form.

Inputs

Manual inputs and workflow inputs use the same format:

Field	Description
Slug	The key sent to the API. Lowercase letters, digits and underscores, starting with a letter (for example user_email). Unique within the action
Label	What admins see
Type	Text, Number, Yes / No, Date or Choice
Choices	For Choice inputs, a comma-separated list of accepted values, for example low, medium, high
Required	Whether a value is mandatory
Multiple values	Available for Text and Choice inputs only

An input definition URL must return a JSON array in the same format, where kind is text, number, boolean, date or enum:

[
  { "slug": "project", "label": "Project", "kind": "enum", "values": ["Alpha", "Beta"], "required": true },
  { "slug": "reason", "label": "Reason", "kind": "text" }
]

Outputs

Declare the fields of the JSON response you want to reuse in later workflow steps. Each output has a slug, a label and a type, and the slug can be a path into the response:

Response	Output slug	Value
{"status": "created"}	status	created
{"data": {"userId": 42}}	data.userId	42
{"items": [{"id": "a1"}]}	items.0.id	a1

Outputs show up in the workflow variable picker and in branch conditions, for example to continue only when status is created. A path missing from the response gives an empty value. One output can't sit inside another, so you can't declare both data and data.userId.

Action headers

Each action can have up to 20 headers of its own, sent on top of the integration headers. An action header overrides an integration header with the same name. The variables you can insert depend on the context:

Context	Variables
Request	Request, requester, assignee and request form variables
Person	The person's variables
App access request	App access request variables
No target	Company and date variables

Secrets are available in every context.

Use custom actions

On a request or a person

Enabled actions with a manual run mode appear in the Custom actions section of the request side panel, grouped by integration. Person and No target actions also appear in the person's About menu.

Pick an action, fill in the inputs if any, and confirm. Siit runs it right away and shows whether it succeeded, with the error if it failed. A successful run is added to the timeline, for example "Jane ran Create VPN account".

In a workflow

In the workflow editor, each custom integration has its own group of actions. Only enabled actions that match the workflow's trigger are listed. Pick one, fill in its inputs, and save. When the workflow runs on a request, the timeline shows "Create VPN account ran automatically".

In an app access role

Actions with the App access request context can grant and revoke access in tools with no native connector:

1. Open the application's access rules and edit an app access role.

2. Under provisioning or deprovisioning, choose Custom action.

3. Select the custom integration, then the action, and fill in its inputs.

4. To have someone finish the job by hand, add a manual step after the custom action.

If no deprovisioning action is set, revoking access creates a manual task for the app owner. See App access policies.

With Assist

When integration actions are enabled for Assist in your workspace, Assist can find and run the custom actions that have a manual run mode. It only sees the actions the person it works for is allowed to run.

Permissions

• Configuring custom integrations and actions requires Can configure integrations.

• Running actions and seeing their run history is granted per integration in role permissions, and each custom integration counts as a separate integration. A new custom integration is only granted to Super admin roles. Grant it to other roles as needed in Roles & permissions.

• A role without access to an integration doesn't see its actions anywhere: not on requests, not in the workflow editor, not in app access roles.

Enable, disable or delete an action

State	Effect
Enabled	Offered on requests and people (with a manual run mode), in workflows and in app access roles
Disabled	No longer offered for new uses. Workflows and app access roles that already use it keep running it
Deleted	Hidden everywhere. Workflows and app access roles that use it stop working. Its run history is kept

{% hint style="warning" %} To stop an action from running at all, remove it from the workflows and app access roles that use it, then disable or delete it. Deleting a custom integration also deletes all its actions. {% endhint %}

Test a new integration

There is no built-in health check. To test the URL, the authentication and the API permissions in one go, create a read-only GET action on the API's "current user" or "status" endpoint, set its manual run mode to Without inputs, enable it and run it from a test request.

Limits and behavior

Topic	Behavior
Timeout	Each run must complete within about 20 seconds
Response	Must be a JSON object of 256 KB or less. Text outputs longer than 10,000 characters are cut before reaching workflow variables
Retries	None. Each call is sent exactly once, so the third party never receives the same request twice
Missing secret	If a header uses a secret that no longer exists, the run fails before anything is sent. Siit never sends an empty credential
Edited actions	Workflows always use the action's current definition. If you rename or remove an input a workflow fills in, that workflow's runs fail and nothing is sent until you update the step
Network	HTTPS and public addresses only, no redirects

Troubleshooting

Symptom	What to check
The action doesn't appear anywhere	It is enabled, its context matches the page or the workflow trigger, and your role has access to the integration
The action doesn't appear on requests or people	Its manual run mode isn't Not offered, and its context isn't App access request
The action doesn't appear in the workflow editor	Offer to workflows is on
The third party receives {{...}} as text	The variable was typed by hand. Insert it with the picker or the {{ autocomplete
A workflow fails after an action was edited	An input used by the workflow was renamed or removed. Update the workflow step

Manage custom integrations with the API and MCP

Custom integrations and actions can also be managed outside the Siit interface, for example to keep them in version control or to have an AI client set them up.

• Siit API: /v1/custom_integrations and /v1/custom_integrations/:uid/custom_actions support list, read, create, update and delete. Each action's run history is at …/custom_actions/:uid/executions. Requires the admin.custom_integrations.read and admin.custom_integrations.write scopes. Logos can only be uploaded from the Siit interface.

• Siit MCP: tools such as list_custom_integrations, create_custom_integration, create_custom_action and update_custom_action let an MCP client like Claude or Cursor configure integrations and actions.

The API and MCP also support settings the interface doesn't offer yet:

• PATCH as an HTTP method.

• A custom request body (body): free text such as JSON, GraphQL or plain text, with the same variables as headers, plus input values as {{inputs.<slug>}}. Values are inserted as raw text, so check that the result is valid, and set Content-Type yourself in the custom headers.

• No authentication (auth_method: none), for APIs that expect their credentials in custom headers only.

Data model

Resource	Description
Custom integration	A third-party API: name, logo, documentation URL, credentials and shared headers
Custom action	One operation on that API: context, method, URL, inputs, outputs and its own headers. Belongs to one integration
Execution	One run of an action: what triggered it (an admin, a workflow or an app access role), the inputs, the response and the status. It keeps the version of the action it ran, so later edits don't change past history