Stackurity Start free trial

API reference Integrations

Integrations

72 operations. Base URL https://app.stackurity.dev/api/v1 on Stackurity Cloud; see authentication.

Report a Launch Stack role (called by the stack)

POST /aws/callback

Role: none (signed single-use token; rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

AWS connections

GET /aws/connections

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start an AWS connection (Launch Stack link)

POST /aws/connections

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

An AWS connection

GET /aws/connections/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove an AWS connection

DELETE /aws/connections/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Agent installs through SSM

GET /aws/connections/{id}/installs

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Install the agent on EC2 instances through SSM

POST /aws/connections/{id}/installs

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

EC2 instances SSM manages

GET /aws/connections/{id}/instances

Role: admin

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

ParameterInTypeDescription
id requiredpathstring
regionquerystringone of the connection's regions

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

New Launch Stack link

POST /aws/connections/{id}/launch

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Verify an AWS connection's role (paste the role ARN)

POST /aws/connections/{id}/verify

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Commands that connect an Azure subscription to this workspace (the Stackurity app, or a client secret)

GET /cloud-setup/azure

Role: admin

Parameters

ParameterInTypeDescription
tenant_id requiredquerystring
subscription_id requiredquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Commands that connect a Google Cloud project to this workspace (workload identity, or a service account key)

GET /cloud-setup/gcp

Role: admin

Parameters

ParameterInTypeDescription
project_id requiredquerystring
project_number requiredquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Failing connections, expiring or unused API tokens and old stored secrets

GET /credentials/health

Role: admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Integrations

GET /integrations

Role: engineer

List integrations, trigger a run

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create an integration

POST /integrations

Role: admin

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

DigitalOcean connection status (the token is never returned)

GET /integrations/digitalocean

Role: admin

Whether a DigitalOcean API token is stored, and whether stored secrets are available

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

DigitalOcean droplets and whether an agent covers each

GET /integrations/digitalocean/droplets

Role: admin

Lists the account's droplets (optionally by tag) with coverage: reporting, enrolled or not_covered. Stackurity installs nothing on droplets

Parameters

ParameterInTypeDescription
tagquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Store a DigitalOcean API token (encrypted; never returned)

PUT /integrations/digitalocean/token

Role: admin

Checks the token can list droplets, then stores it as the encrypted workspace secret digitalocean-token

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Delete the stored DigitalOcean API token

DELETE /integrations/digitalocean/token

Role: admin

Deletes the stored DigitalOcean API token

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Compliance evidence connections (Vanta, Drata) (licensed edition)

GET /integrations/evidence

Role: admin Licensed build only

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Connect Drata with an API key (licensed edition)

POST /integrations/evidence/drata

Role: admin Licensed build only

{"api_key", "region", "drata_workspace_id"}: the key is checked with one read call, then stored sealed

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Connect Vanta (licensed edition)

POST /integrations/evidence/vanta/connect

Role: admin Licensed build only

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Vanta documents the evidence file can go to (licensed edition)

GET /integrations/evidence/vanta/documents

Role: admin Licensed build only

Lists the connected Vanta account's documents (id, title)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Finish Connect Vanta (licensed edition)

POST /integrations/evidence/vanta/oauth

Role: admin Licensed build only

{"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

FieldTypeDescription
codestring
state requiredstring
errorstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change a compliance evidence connection (licensed edition)

PUT /integrations/evidence/{vendor}

Role: admin Licensed build only

{"interval_hours"?, "status"?, "vanta_document_id"?}

Parameters

ParameterInTypeDescription
vendor requiredpathstringOne of vanta, drata.

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Disconnect Vanta or Drata (licensed edition)

DELETE /integrations/evidence/{vendor}

Role: admin Licensed build only

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

ParameterInTypeDescription
vendor requiredpathstringOne of vanta, drata.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Recent syncs of a compliance evidence connection (licensed edition)

GET /integrations/evidence/{vendor}/runs

Role: admin Licensed build only

The newest 50 syncs: status, counts and error

Parameters

ParameterInTypeDescription
vendor requiredpathstringOne of vanta, drata.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Sync to Vanta or Drata now (licensed edition)

POST /integrations/evidence/{vendor}/sync

Role: admin Licensed build only

Queues a sync (202); at most once every 5 minutes per connection

Parameters

ParameterInTypeDescription
vendor requiredpathstringOne of vanta, drata.

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

GitHub App status and installations

GET /integrations/github

Role: engineer

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Install on GitHub

POST /integrations/github/install

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Disconnect a GitHub account

DELETE /integrations/github/installations/{installation_id}

Role: admin

Switches its repositories' integrations off (history kept), removes the binding and uninstalls the app from that GitHub account (uninstalled_on_github)

Parameters

ParameterInTypeDescription
installation_id requiredpathinteger

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List an installation's repositories again

POST /integrations/github/installations/{installation_id}/sync

Role: admin

Queues a listing of the repositories the installation grants on GitHub (202)

Parameters

ParameterInTypeDescription
installation_id requiredpathinteger

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Finish Install on GitHub

POST /integrations/github/setup

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

GitHub App webhook (verified by GitHub's signature)

POST /integrations/github/webhook

Role: none: GitHub's signature (the app's webhook secret)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Connect GitLab status and connected groups

GET /integrations/gitlab

Role: engineer

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Connect GitLab

POST /integrations/gitlab/connect

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Connect a GitLab group

POST /integrations/gitlab/connections

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Choose a connected group's Stackurity project

PATCH /integrations/gitlab/connections/{id}

Role: admin

{"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

ParameterInTypeDescription
id requiredpathinteger

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Disconnect a GitLab group

DELETE /integrations/gitlab/connections/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathinteger

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Authorise read-only access, or clean up on GitLab

POST /integrations/gitlab/connections/{id}/authorize

Role: admin

{"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

ParameterInTypeDescription
id requiredpathinteger

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List a connected group's projects again

POST /integrations/gitlab/connections/{id}/sync

Role: admin

Queues a listing of the group's projects on GitLab (202)

Parameters

ParameterInTypeDescription
id requiredpathinteger

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Finish an authorisation at GitLab

POST /integrations/gitlab/oauth

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Connect GitLab webhook (verified by the connection's secret token)

POST /integrations/gitlab/webhook/{id}

Role: none: GitLab's secret token (the connection's)

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

ParameterInTypeDescription
id requiredpathinteger

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List Jira connections

GET /integrations/jira/connections

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Disconnect Jira

DELETE /integrations/jira/connections/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List a Jira site's projects

GET /integrations/jira/connections/{id}/projects

Role: admin

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

ParameterInTypeDescription
id requiredpathstring
site requiredquerystringThe site's cloud id
qquerystringText the key or name contains

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Read a Jira project's issue types and statuses

GET /integrations/jira/connections/{id}/projects/{key}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring
key requiredpathstring
site requiredquerystringThe site's cloud id

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Connect Jira

POST /integrations/jira/install

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Finish Connect Jira

POST /integrations/jira/oauth

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Cancel Connect PagerDuty

POST /integrations/pagerduty/cancel

Role: admin

{"session"}: deletes the session and its PagerDuty token. 204

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Connect PagerDuty

POST /integrations/pagerduty/connect

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add the Stackurity integration to a PagerDuty service

POST /integrations/pagerduty/finish

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Exchange the PagerDuty code and list services

POST /integrations/pagerduty/oauth

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List the connected account's PagerDuty services

POST /integrations/pagerduty/services

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List a container registry's repositories

POST /integrations/registry/discover

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Slack's interactivity Request URL (verified by Slack's signature)

POST /integrations/slack/actions

Role: none: Slack's signature (see Acting from Slack)

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

FieldTypeDescription
payloadstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Slack app events (verified by Slack's signature)

POST /integrations/slack/events

Role: none: Slack's signature (the app's signing secret)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Add to Slack

POST /integrations/slack/install

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Finish Add to Slack

POST /integrations/slack/oauth

Role: admin

{"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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start Add to Teams

POST /integrations/teams/install

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

What became of an Add to Teams code

GET /integrations/teams/install/{id}

Role: admin

status pending, expired, connected (with channel) or failed, and expires_at. 404 for another person's code

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The Teams app's messaging endpoint (verified by a Bot Framework JWT)

POST /integrations/teams/messages

Role: none: a Bot Framework token for the app

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Change an integration

PATCH /integrations/{id}

Role: admin

Manage integrations

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete an integration

DELETE /integrations/{id}

Role: admin

Manage integrations

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Images a container registry integration tracks

GET /integrations/{id}/images

Role: engineer

The images (digests) a container registry integration chose, stopped tracking, or found removed

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Run an integration now

POST /integrations/{id}/run

Role: engineer

List integrations, trigger a run

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Background job queue

GET /jobs

Role: admin

Parameters

ParameterInTypeDescription
statequerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Status of one background job

GET /jobs/{id}

Role: engineer

Status of one job, e.g. after Run now

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Installed plugins with their declared permissions, credentials and network access

GET /plugins

Role: admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Stored secrets of the organisation (names only, never values)

GET /secrets

Role: admin

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Store a secret (encrypted; never returned)

PUT /secrets/{name}

Role: admin

Parameters

ParameterInTypeDescription
name requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Delete a stored secret

DELETE /secrets/{name}

Role: admin

Parameters

ParameterInTypeDescription
name requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError