API reference Integrations
Integrations
Report a Launch Stack role (called by the stack)
POST /aws/callback
Called once by the stack's custom resource with {"role_arn", "external_id", "stack_id"} and Authorization: Bearer <token>, the signed single-use token from the Launch Stack link. The token names the connection, its workspace and external ID; it is used up by the first request, expires after 24 hours and is replaced by a new link. The server then assumes the role with the external ID (and checks it cannot without) and activates the connection. Every refusal of a token is the same 403. Outside the session and CSRF checks
Request body
application/json, required: object
Responses
AWS connections
GET /aws/connections
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): the connections, and enabled (the server has an AWS principal, STACKURITY_AWS_PRINCIPAL_ARN), principal, launch_stack (the template is hosted in S3, STACKURITY_AWS_TEMPLATE_URL), template_download and the IAM actions the role grants (permissions, agent_install_permissions)
Responses
Start an AWS connection (Launch Stack link)
POST /aws/connections
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): regions (1–40, scanned), stack_region (where the stack is created; default the first region), agent_install (adds the SSM permissions). Returns the connection with its generated external ID and launch: quick_create_url (empty without an S3-hosted template), template_download, cli (the same stack with the AWS CLI), external_id, principal, and callback (the stack reports its role by itself; false when this server's address is not https, then the role ARN is pasted). 404 when the server has no AWS principal
Request body
application/json, required: object
Responses
An AWS connection
GET /aws/connections/{id}
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): status (pending, active, failed), role_arn, account_id, last_error, integration_id and integration_removed
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Remove an AWS connection
DELETE /aws/connections/{id}
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): removes the connection and its integration. The role stays in the AWS account until its stack is deleted
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Agent installs through SSM
GET /aws/connections/{id}/installs
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): the agent installs sent through SSM, newest first, after reading from SSM how the unfinished ones went: status pending, running, success, failed or timed_out, and detail (the end of the command's output). The code of a failed or timed-out install is revoked. refresh_error says why SSM could not be read
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Install the agent on EC2 instances through SSM
POST /aws/connections/{id}/installs
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): region and instances (1–25 of {"instance_id", "computer_name"}). Each instance gets its own single-use enrollment code (two hours), sent in an AWS-RunShellScript command that runs this server's installer; the code is not stored. Answers 202 with one install per instance
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
EC2 instances SSM manages
GET /aws/connections/{id}/instances
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): the instances SSM manages in one of the connection's regions (?region=, default the first), each with eligible (Linux and online), asset_id (a host already reporting with that hostname) and last_install. Needs the stack's agent install option; AWS errors answer 502
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
region | query | string | one of the connection's regions |
Responses
New Launch Stack link
POST /aws/connections/{id}/launch
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): a new link for a connection that is not active (stack_region, agent_install); the earlier link's token stops working
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Verify an AWS connection's role (paste the role ARN)
POST /aws/connections/{id}/verify
Connect an AWS account with a CloudFormation stack (docs/install.md, "AWS managed services"): role_arn (the stack's RoleArn output; empty verifies the one recorded again). The role must be assumable with the connection's external ID and refused without it; then the connection is active, its aws-managed integration is created and a first run is queued. A failure is recorded as status: failed with last_error
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Commands that connect an Azure subscription to this workspace (the Stackurity app, or a client secret)
GET /cloud-setup/azure
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
tenant_id required | query | string | |
subscription_id required | query | string |
Responses
Commands that connect a Google Cloud project to this workspace (workload identity, or a service account key)
GET /cloud-setup/gcp
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
project_id required | query | string | |
project_number required | query | string |
Responses
Failing connections, expiring or unused API tokens and old stored secrets
GET /credentials/health
Responses
Integrations
GET /integrations
List integrations, trigger a run
Responses
Create an integration
POST /integrations
Request body
application/json, required: object
Responses
DigitalOcean connection status (the token is never returned)
GET /integrations/digitalocean
Whether a DigitalOcean API token is stored, and whether stored secrets are available
Responses
DigitalOcean droplets and whether an agent covers each
GET /integrations/digitalocean/droplets
Lists the account's droplets (optionally by tag) with coverage: reporting, enrolled or not_covered. Stackurity installs nothing on droplets
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
tag | query | string |
Responses
Store a DigitalOcean API token (encrypted; never returned)
PUT /integrations/digitalocean/token
Checks the token can list droplets, then stores it as the encrypted workspace secret digitalocean-token
Request body
application/json, required: object
Responses
Delete the stored DigitalOcean API token
DELETE /integrations/digitalocean/token
Deletes the stored DigitalOcean API token
Responses
Compliance evidence connections (Vanta, Drata) (licensed edition)
GET /integrations/evidence
Whether the organisation's plan includes the Compliance add-on (compliance_addon), whether each vendor is available on this server, and the organisation's connection to it, with its schedule and last sync; tokens and API keys are never returned. Also answers without the add-on (after a downgrade), so the connections can be disconnected
Responses
Connect Drata with an API key (licensed edition)
POST /integrations/evidence/drata
{"api_key", "region", "drata_workspace_id"}: the key is checked with one read call, then stored sealed
Request body
application/json, required: object
Responses
Start Connect Vanta (licensed edition)
POST /integrations/evidence/vanta/connect
{"region"} (us, eu or aus); answers authorize_url, Vanta's consent page, with a single-use state (10 minutes). 404 not_configured without the operator's Vanta app
Request body
application/json, required: object
Responses
Vanta documents the evidence file can go to (licensed edition)
GET /integrations/evidence/vanta/documents
Lists the connected Vanta account's documents (id, title)
Responses
Finish Connect Vanta (licensed edition)
POST /integrations/evidence/vanta/oauth
{"code", "state"} (or {"state", "error"} after a cancel), posted by the dashboard page /integrations/vanta/oauth/callback Vanta sends the browser back to. The state must be the caller's, from this organisation, unused and fresh; it is used up by the first attempt. Answers {"connection", "reconnected"} (201, or 200 for a reconnect). Errors: 400 access_denied, 400 state, 400 or 502 exchange_failed, 404 not_configured, 402 plan_required, 403 forbidden (API tokens, assistants and sessions that have not met the two-factor policy too)
Request body
application/json, required: object
| Field | Type | Description |
|---|---|---|
code | string | |
state required | string | |
error | string |
Responses
Change a compliance evidence connection (licensed edition)
PUT /integrations/evidence/{vendor}
{"interval_hours"?, "status"?, "vanta_document_id"?}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
vendor required | path | string | One of vanta, drata. |
Request body
application/json, required: object
Responses
Disconnect Vanta or Drata (licensed edition)
DELETE /integrations/evidence/{vendor}
Deletes the connection and its tokens or key, also without the Compliance add-on (for Vanta, after asking Vanta to suspend the grant with a refreshed token, best effort; token_suspended says whether it worked)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
vendor required | path | string | One of vanta, drata. |
Responses
Recent syncs of a compliance evidence connection (licensed edition)
GET /integrations/evidence/{vendor}/runs
The newest 50 syncs: status, counts and error
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
vendor required | path | string | One of vanta, drata. |
Responses
Sync to Vanta or Drata now (licensed edition)
POST /integrations/evidence/{vendor}/sync
Queues a sync (202); at most once every 5 minutes per connection
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
vendor required | path | string | One of vanta, drata. |
Responses
GitHub App status and installations
GET /integrations/github
configured (whether this server has the Stackurity GitHub App; with app_url) and installations, this organisation's GitHub accounts with status (active, suspended, deleted), note and the number of repositories
Responses
Start Install on GitHub
POST /integrations/github/install
{"return_to": "/settings/integrations"} (a dashboard path). Answers url, the app's install page on GitHub with a single-use state bound to the caller and organisation (10 minutes). 404 not_configured without the Stackurity GitHub App (STACKURITY_GITHUB_APP_ID, ...)
Request body
application/json, required: object
Responses
Disconnect a GitHub account
DELETE /integrations/github/installations/{installation_id}
Switches its repositories' integrations off (history kept), removes the binding and uninstalls the app from that GitHub account (uninstalled_on_github)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
installation_id required | path | integer |
Responses
List an installation's repositories again
POST /integrations/github/installations/{installation_id}/sync
Queues a listing of the repositories the installation grants on GitHub (202)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
installation_id required | path | integer |
Responses
Finish Install on GitHub
POST /integrations/github/setup
{"state", "code", "installation_id", "setup_action"} from GitHub's redirect to /integrations/github/callback. The state must be the caller's, in this organisation, unused and fresh (400 github_state otherwise, before GitHub is called). The installation must be visible to the person's GitHub account (from code) and confirmed with the app's JWT (403 github_installation), and not held by another organisation (409 github_installation_taken). 201: installation, return_to
Request body
application/json, required: object
Responses
GitHub App webhook (verified by GitHub's signature)
POST /integrations/github/webhook
The Stackurity GitHub App's webhook URL. 401 unless X-Hub-Signature-256 is the HMAC-SHA256 of the body with the app's webhook secret; 400 without X-GitHub-Event or X-GitHub-Delivery; a delivery already handled answers {"result": "duplicate"}. Handles installation, installation_repositories and push; 404 without the app
Request body
application/json, required: object
Responses
Connect GitLab status and connected groups
GET /integrations/gitlab
configured (whether this server offers Connect GitLab; with gitlab_url) and connections, this organisation's connected GitLab groups with group_path, credential_kind (group_token, oauth, none), credential_expires, webhook (active, not_permitted, none), status (active, needs_credential, expired), note and the number of projects
Responses
Start Connect GitLab
POST /integrations/gitlab/connect
{"return_to": "/settings/integrations"}. Answers url, GitLab's consent page for the api scope with a single-use state bound to the caller and organisation (10 minutes). 404 not_configured without Connect GitLab; 409 secrets_disabled without STACKURITY_SECRET_KEY
Request body
application/json, required: object
Responses
Connect a GitLab group
POST /integrations/gitlab/connections
{"pick", "group_id", "project_id"}: project_id is the Stackurity project the group's assets are added to (0 for none; left out, the project chosen in the switcher). The caller's GitLab account must be a member (Reporter or above) of the group (403 gitlab_group); a group connected elsewhere, or above or below one, is refused (409 gitlab_group_taken). 201: connection, needs_readonly, notes, return_to
Request body
application/json, required: object
Responses
Choose a connected group's Stackurity project
PATCH /integrations/gitlab/connections/{id}
{"project_id"}: the Stackurity project the group's assets are added to when first scanned (0 for none). The group's assets already scanned that are in no project are added to it now (assets_added); assets already in a project stay. 200: connection, assets_added
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | integer |
Request body
application/json, required: object
Responses
Disconnect a GitLab group
DELETE /integrations/gitlab/connections/{id}
Removes the connection (its sealed credential and webhook secret with it); its projects' integrations are switched off with a note, assets and history kept. Revokes the stored credential at GitLab where it can (credential_revoked); webhook_left_on_gitlab when the group webhook remains (use the cleanup authorisation to delete it)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | integer |
Responses
Authorise read-only access, or clean up on GitLab
POST /integrations/gitlab/connections/{id}/authorize
{"purpose": "readonly" | "cleanup", "return_to"}. Answers url, GitLab's consent page: read_api read_repository for readonly (the credential kept when a group access token is not allowed), api for cleanup (deletes the webhook and the group access token on GitLab, then disconnects)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | integer |
Request body
application/json, required: object
Responses
List a connected group's projects again
POST /integrations/gitlab/connections/{id}/sync
Queues a listing of the group's projects on GitLab (202)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | integer |
Responses
Finish an authorisation at GitLab
POST /integrations/gitlab/oauth
{"state", "code"} from GitLab's redirect to /integrations/gitlab/callback. The state must be the caller's, in this organisation, unused and fresh (400 gitlab_state, before GitLab is called); the token must have exactly the scopes asked (400 gitlab_scopes). For Connect GitLab answers pick (single use, 10 minutes) and groups (id, full_path, name, owner); for a read-only authorisation 201 connection; for a cleanup webhook_deleted, token_revoked, disconnected
Request body
application/json, required: object
Responses
Connect GitLab webhook (verified by the connection's secret token)
POST /integrations/gitlab/webhook/{id}
A connected group's webhook URL. 401 unless X-Gitlab-Token is the connection's secret token; 400 without X-Gitlab-Event or X-Gitlab-Event-UUID; a delivery already handled answers {"result": "duplicate"}. A Push Hook to a project's default branch that changes a lockfile or manifest queues its scan; other events list the group again; 404 without Connect GitLab
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | integer |
Request body
application/json, required: object
Responses
List Jira connections
GET /integrations/jira/connections
Connect Jira connections of this organisation: id, sites (id the cloud id, name, url), scopes, status (active or reconnect_needed), status_reason, connected_by, connected_at, refreshed_at. Tokens are never returned
Responses
Disconnect Jira
DELETE /integrations/jira/connections/{id}
Deletes the connection and its tokens; the Jira channels using it are switched off with a note (channels_disabled). Atlassian has no API to revoke a grant: revoke_url is where the person removes the app from their Atlassian account
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
List a Jira site's projects
GET /integrations/jira/connections/{id}/projects
The projects of a site of the connection (key, name), read with its token, for setting up a channel. 409 jira_reconnect when the connection needs reconnecting; 502 when Jira refuses
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
site required | query | string | The site's cloud id |
q | query | string | Text the key or name contains |
Responses
Read a Jira project's issue types and statuses
GET /integrations/jira/connections/{id}/projects/{key}
issue_types (name, subtask), statuses by issue type (name, category: new, indeterminate or done) and the site's priorities, for setting up a channel
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string | |
key required | path | string | |
site required | query | string | The site's cloud id |
Responses
Start Connect Jira
POST /integrations/jira/install
{"return_to": "/settings/integrations", "connection_id": 0} (a dashboard path; connection_id to reconnect a connection of this organisation). Answers url, Atlassian's consent page with a single-use state bound to the caller and organisation (10 minutes). 404 not_configured without the Stackurity Atlassian app (STACKURITY_JIRA_CLIENT_ID, STACKURITY_JIRA_CLIENT_SECRET)
Request body
application/json, required: object
Responses
Finish Connect Jira
POST /integrations/jira/oauth
{"code", "state"} from Atlassian's redirect to /integrations/jira/oauth/callback. The state must be the caller's, in this organisation, unused and fresh (400 jira_state otherwise, before Atlassian is called). Stores the grant sealed and answers connection (its Jira sites, never the tokens), return_to and reconnected (201 new, 200 reconnected); 400 jira_no_site; 502 jira_refused
Request body
application/json, required: object
Responses
Cancel Connect PagerDuty
POST /integrations/pagerduty/cancel
{"session"}: deletes the session and its PagerDuty token. 204
Request body
application/json, required: object
Responses
Start Connect PagerDuty
POST /integrations/pagerduty/connect
{"return_to"} (a dashboard path). Answers url, PagerDuty's consent page asking for services.read services.write, with a PKCE S256 challenge and a state that works once, for 10 minutes, for the caller in this organisation. 404 not_configured without the PagerDuty app
Request body
application/json, required: object
Responses
Add the Stackurity integration to a PagerDuty service
POST /integrations/pagerduty/finish
{"session", "service_id"}. Deletes the session and its token, adds an Events API v2 integration named Stackurity to the service and stores its routing key as the channel's secret (never returned). 201: channel, return_to, service_name; 200 with reused when the service already had a channel. 400 pagerduty_state; 502 pagerduty_refused with PagerDuty's reason
Request body
application/json, required: object
Responses
Exchange the PagerDuty code and list services
POST /integrations/pagerduty/oauth
{"code", "state"} from PagerDuty's redirect to /integrations/pagerduty/oauth/callback. 200: session (10 minutes, the caller only), region (us or eu), return_to, services and more. 400 pagerduty_state for a state that is unknown, used, expired or someone else's, before PagerDuty is called; 502 pagerduty_scope when a scope was not granted, 502 pagerduty_refused otherwise
Request body
application/json, required: object
Responses
List the connected account's PagerDuty services
POST /integrations/pagerduty/services
{"session", "query"}: services and more (more than 1,000). 400 pagerduty_state for a session that is not the caller's or has expired
Request body
application/json, required: object
Responses
List a container registry's repositories
POST /integrations/registry/discover
List the repositories of a registry before connecting it, with whether the configuration keeps each; the secret is used, never returned
Request body
application/json, required: object
Responses
Slack's interactivity Request URL (verified by Slack's signature)
POST /integrations/slack/actions
Slack's interactivity Request URL. Form-encoded payload as Slack sends it, with X-Slack-Request-Timestamp and X-Slack-Signature. 200 once verified (the answer goes to Slack's response_url), 401 for any request that cannot be verified, is older than 5 minutes or was already received, 400 for a verified payload with an unexpected team, user or response_url
Request body
application/x-www-form-urlencoded, required: object
| Field | Type | Description |
|---|---|---|
payload | string |
Responses
Slack app events (verified by Slack's signature)
POST /integrations/slack/events
The Stackurity Slack app's Event Subscriptions Request URL: url_verification, and app_uninstalled or tokens_revoked, which disable that Slack workspace's app channels in every organisation and delete their webhooks and tokens. 401 for a request the app's signing secret does not verify or older than 5 minutes; 404 without the app
Request body
application/json, required: object
Responses
Start Add to Slack
POST /integrations/slack/install
{"return_to": "/settings/integrations"} (a dashboard path). Answers url, Slack's consent page with a single-use state bound to the caller and organisation (10 minutes). 404 not_configured without the Stackurity Slack app (STACKURITY_SLACK_CLIENT_ID, ...)
Request body
application/json, required: object
Responses
Finish Add to Slack
POST /integrations/slack/oauth
{"code", "state"} from Slack's redirect to /integrations/slack/oauth/callback. The state must be the caller's, in this organisation, unused and fresh (400 slack_state otherwise). Creates a Slack channel for the webhook Slack returned (201: channel, return_to, team_name, slack_channel); 502 slack_refused when Slack does not complete the install
Request body
application/json, required: object
Responses
Start Add to Teams
POST /integrations/teams/install
Answers id, code (single use, 15 minutes, for the caller in this organisation; their earlier unused code stops working), expires_at and install_url (opens the app in Teams). Sending the code to the bot in a Teams channel connects that channel. 404 not_configured without the Stackurity Teams app (STACKURITY_TEAMS_APP_ID, ...)
Request body
application/json, required: object
Responses
What became of an Add to Teams code
GET /integrations/teams/install/{id}
status pending, expired, connected (with channel) or failed, and expires_at. 404 for another person's code
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
The Teams app's messaging endpoint (verified by a Bot Framework JWT)
POST /integrations/teams/messages
Bot Framework activities from Microsoft Teams. Every request needs Authorization: Bearer with a JWT the Bot Framework signed (RS256, a key endorsed for msteams), issued by https://api.botframework.com for the app's ID, current, whose serviceurl claim is the activity's serviceUrl; otherwise 401. 403 for a serviceUrl that is not a Teams Bot Connector host. A message with an Add to Teams code connects its channel; the app removed from a team or a channel deleted switches the matching integrations off. 404 without the app
Request body
application/json, required: object
Responses
Change an integration
PATCH /integrations/{id}
Manage integrations
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Delete an integration
DELETE /integrations/{id}
Manage integrations
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Images a container registry integration tracks
GET /integrations/{id}/images
The images (digests) a container registry integration chose, stopped tracking, or found removed
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Run an integration now
POST /integrations/{id}/run
List integrations, trigger a run
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Background job queue
GET /jobs
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
state | query | string |
Responses
Status of one background job
GET /jobs/{id}
Status of one job, e.g. after Run now
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Installed plugins with their declared permissions, credentials and network access
GET /plugins
Responses
Stored secrets of the organisation (names only, never values)
GET /secrets
Responses
Store a secret (encrypted; never returned)
PUT /secrets/{name}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
name required | path | string |
Request body
application/json, required: object
Responses
Delete a stored secret
DELETE /secrets/{name}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
name required | path | string |