Integrations (v1)

This document uses the v1 API. For more details, see the v1 API.

Add new integration

Add new integration for given organization.

Required permissions

• View Organization

• View Integrations

• Edit Integrations

POSThttps://api.snyk.io/v1/org/{orgId}/integrations

Path parameters

orgId*string

The organization ID. The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Body

application/json; charset=utf-8

type*IntegrationType

acrartifactory-crazure-reposbitbucket-cloudbitbucket-serverdigitalocean-crdocker-hubecrgcrgithubgithub-crgithub-enterprisegithub-cloud-appgitlabgitlab-crgoogle-artifact-crharbor-crnexus-crquay-cr

credentials*IntegrationCredentials (one of)

AcrCredentialsArtifactoryCrCredentialsAzureReposCredentialsBitbucketCloudCredentialsBitbucketServerCredentialsDigitalOceanCrCredentialsDockerHubCredentialsEcrCredentialsGcrCredentialsGitHubCredentialsGitHubCrCredentialsGitHubEnterpriseCredentialsGitLabCredentialsGitLabCrCredentialsGoogleArtifactCrCredentialsHarborCrCredentialsNexusCrCredentialsQuayCrCredentials

Response

200

Body

application/json; charset=utf-8

id*string

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "type": "acr",
      "credentials": {
        "username": "text",
        "password": "text",
        "registryBase": "text"
      }
    }),
});
const data = await response.json();

Response

200

{
  "id": "9a3e5d90-b782-468a-a042-9a2073736f0b"
}

List

Required permissions

• View Organization

• View Integrations

GEThttps://api.snyk.io/v1/org/{orgId}/integrations

Path parameters

orgId*string

The organization public ID. The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Header parameters

Response

200

Body

application/json; charset=utf-8

object

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations', {
    method: 'GET',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
});
const data = await response.json();

Response

200

{
  "github": "9a3e5d90-b782-468a-a042-9a2073736f0b",
  "gitlab": "1b3e3d90-c678-347a-n232-6a3453738h1e",
  "bitbucket-cloud": "6jje4c92-e7rn-t59a-f456-8n5675432fe9"
}

Get existing integration by type

Required permissions

• View Organization - View Integrations

GEThttps://api.snyk.io/v1/org/{orgId}/integrations/{type}

Path parameters

orgId*string

The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

type*all of

Integration type.

Header parameters

Response

200

Body

application/json; charset=utf-8

idstring

Alphanumeric UUID including - with a limit of 36 characters

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{type}', {
    method: 'GET',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
});
const data = await response.json();

Response

200

{
  "id": "9a3e5d90-b782-468a-a042-9a2073736f0b"
}

Update existing integration

• Update integration's credentials for given organization. Integration must be not brokered

• Enable or disable brokered integration for given organization. Credentials required for disabling brokered integration

Examples in right section:

1. Set up a broker for an existing integration

2. Update credentials for an existing non-brokered integration

3. Disable broker for an existing integration

Required permissions

• View Organization

• View Integrations

• Edit Integrations

PUThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}

Path parameters

orgId*string

The organization ID. The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

The unique identifier for the configured integration. This can be found on the Integration page in the Settings area for all integrations that have been configured.

Example: "9a3e5d90-b782-468a-a042-9a2073736f0b"

Body

application/json; charset=utf-8

type*IntegrationType

acrartifactory-crazure-reposbitbucket-cloudbitbucket-serverdigitalocean-crdocker-hubecrgcrgithubgithub-crgithub-enterprisegithub-cloud-appgitlabgitlab-crgoogle-artifact-crharbor-crnexus-crquay-cr

broker*BrokerSettings

any

Response

200

Body

application/json; charset=utf-8

id*string

brokerToken*string

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "type": "github",
      "broker": {
        "enabled": true
      }
    }),
});
const data = await response.json();

Response

200

{
  "id": "9a3e5d90-b782-468a-a042-9a2073736f0b",
  "brokerToken": "4a18d42f-0706-4ad0-b127-24078731fbed"
}

Update

Required permissions

• View Organization

• View Integrations

• Edit Integrations

PUThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/settings

Path parameters

orgId*string

The organization ID. The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

The unique identifier for the configured integration. This can be found on the Integration page in the Settings area for all integrations that have been configured.

Example: "9a3e5d90-b782-468a-a042-9a2073736f0b"

Body

application/json; charset=utf-8

autoDepUpgradeLimitnumber

A limit on how many automatic dependency upgrade PRs can be opened simultaneously

autoDepUpgradeIgnoredDependenciesarray of string

A list of strings defining what dependencies should be ignored

autoDepUpgradeEnabledboolean

Defines if the functionality is enabled

autoDepUpgradeMinAgenumber

The age (in days) that an automatic dependency check is valid for

pullRequestFailOnAnyVulnsboolean

If an opened PR should fail to be validated if any vulnerable dependencies have been detected

pullRequestFailOnlyForHighSeverityboolean

If an opened PR only should fail its validation if any dependencies are marked as being of high severity

pullRequestTestEnabledboolean

If opened PRs should be tested

pullRequestAssignmentstring

assign Snyk pull requests

autoRemediationPrsall of

manualRemediationPrsall of

dockerfileSCMEnabledboolean

If true, will automatically detect and scan Dockerfiles in your Git repositories, surface base image vulnerabilities and recommend possible fixes

any

Response

200

Body

application/json; charset=utf-8

autoDepUpgradeLimitnumber

A limit on how many automatic dependency upgrade PRs can be opened simultaneously

autoDepUpgradeIgnoredDependenciesarray of string

A list of strings defining what dependencies should be ignored

autoDepUpgradeEnabledboolean

Defines if the functionality is enabled

autoDepUpgradeMinAgenumber

The age (in days) that an automatic dependency check is valid for

pullRequestFailOnAnyVulnsboolean

If an opened PR should fail to be validated if any vulnerable dependencies have been detected

pullRequestFailOnlyForHighSeverityboolean

If an opened PR only should fail its validation if any dependencies are marked as being of high severity

pullRequestTestEnabledboolean

If opened PRs should be tested

pullRequestAssignmentstring

assign Snyk pull requests

autoRemediationPrsall of

manualRemediationPrsall of

dockerfileSCMEnabledboolean

If true, will automatically detect and scan Dockerfiles in your Git repositories, surface base image vulnerabilities and recommend possible fixes

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/settings', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "autoDepUpgradeLimit": 2,
      "autoDepUpgradeIgnoredDependencies": [],
      "autoDepUpgradeEnabled": false,
      "autoDepUpgradeMinAge": 21,
      "pullRequestTestEnabled": true,
      "pullRequestFailOnAnyVulns": false,
      "pullRequestFailOnlyForHighSeverity": true,
      "pullRequestAssignment": "{\"enabled\":true,\"type\":\"manual\",\"assignees\":[\"username\"]}",
      "autoRemediationPrs": {
        "backlogPrsEnabled": false,
        "backlogPrStrategy": "vuln",
        "freshPrsEnabled": true,
        "usePatchRemediation": false
      },
      "manualRemediationPrs": {
        "useManualPatchRemediation": false
      },
      "dockerfileSCMEnabled": true
    }),
});
const data = await response.json();

Response

200

{
  "autoDepUpgradeLimit": 2,
  "autoDepUpgradeIgnoredDependencies": [],
  "autoDepUpgradeEnabled": false,
  "autoDepUpgradeMinAge": 21,
  "pullRequestFailOnAnyVulns": false,
  "pullRequestFailOnlyForHighSeverity": true,
  "pullRequestTestEnabled": true,
  "pullRequestAssignment": "{\"enabled\":true,\"type\":\"manual\",\"assignees\":[\"username\"]}",
  "autoRemediationPrs": {
    "backlogPrsEnabled": false,
    "backlogPrStrategy": "vuln",
    "freshPrsEnabled": true,
    "usePatchRemediation": false
  },
  "manualRemediationPrs": {
    "useManualPatchRemediation": false
  },
  "dockerfileSCMEnabled": true
}

Retrieve

Required permissions

• View Organization

• View Integrations

GEThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/settings

Path parameters

orgId*string

The organization ID. The API_KEY must have admin access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

The unique identifier for the configured integration. This can be found on the Integration page in the Settings area for all integrations that have been configured.

Example: "9a3e5d90-b782-468a-a042-9a2073736f0b"

Header parameters

Response

200

Body

application/json; charset=utf-8

autoDepUpgradeLimitnumber

A limit on how many automatic dependency upgrade PRs can be opened simultaneously

autoDepUpgradeIgnoredDependenciesarray of string

A list of strings defining what dependencies should be ignored

autoDepUpgradeEnabledboolean

Defines if the functionality is enabled

autoDepUpgradeMinAgenumber

The age (in days) that an automatic dependency check is valid for

pullRequestFailOnAnyVulnsboolean

If an opened PR should fail to be validated if any vulnerable dependencies have been detected

pullRequestFailOnlyForHighSeverityboolean

If an opened PR only should fail its validation if any dependencies are marked as being of high severity

pullRequestTestEnabledboolean

If opened PRs should be tested

pullRequestAssignmentstring

assign Snyk pull requests

autoRemediationPrsall of

manualRemediationPrsall of

dockerfileSCMEnabledboolean

If true, will automatically detect and scan Dockerfiles in your Git repositories, surface base image vulnerabilities and recommend possible fixes

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/settings', {
    method: 'GET',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
});
const data = await response.json();

Response

200

{
  "autoDepUpgradeLimit": 0,
  "autoDepUpgradeIgnoredDependencies": [
    "text"
  ],
  "autoDepUpgradeEnabled": false,
  "autoDepUpgradeMinAge": 0,
  "pullRequestFailOnAnyVulns": false,
  "pullRequestFailOnlyForHighSeverity": false,
  "pullRequestTestEnabled": false,
  "pullRequestAssignment": "text",
  "autoRemediationPrs": {
    "backlogPrsEnabled": false,
    "backlogPrStrategy": {},
    "freshPrsEnabled": false,
    "usePatchRemediation": false
  },
  "manualRemediationPrs": {
    "usePatchRemediation": false
  },
  "dockerfileSCMEnabled": false
}

Clone an integration (with settings and credentials)

Clone an integration, including all of its settings and credentials from one organization to another organization in the same group. This API supports both brokered and non-brokered integrations.

Use this API for when you want to share a Broker token between several Snyk organizations (integrations).

Required permissions

• View Organization

• View Integrations

• Edit Integrations

POSThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/clone

Path parameters

orgId*string

Source organization public ID to clone integration settings from. The API_KEY must have access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

Source integration public ID to clone.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Body

application/json

destinationOrgPublicId*string

The organization public ID. The API_KEY must have access to this organization.

any

Response

200

Body

application/json; charset=utf-8

newIntegrationId*string

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/clone', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "destinationOrgPublicId": "9a3e5d90-b782-468a-a042-9a2073736f0b1"
    }),
});
const data = await response.json();

Response

200

{
  "newIntegrationId": "9a3e5d90-b782-468a-a042-9a2073736f0b"
}

Delete credentials

Required permissions

• View Organization

• View Integrations

• Edit Integrations

Removes any credentials set for this integration. If this is a brokered connection the operation will have no effect.

DELETEhttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication

Path parameters

orgId*string

The organization ID. The API_KEY must have access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

The integration ID.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Header parameters

Response

200

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Switch between broker tokens

Switch the existing broker token with the provisioned token for this integration and any other in the same group. Only perform this action when you have a Broker client running with the provisioned token. This action will fail if there is no token provisioned for this integration or any integration in the same group.

Required permissions

• View Organization

• View Integrations

• Edit Integrations

POSThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication/switch-token

Path parameters

orgId*string

The API_KEY must have access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Header parameters

Response

200

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication/switch-token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Provision new broker token

Issue a new and unique provisional broker token for the brokered integration.

Used for zero down-time token rotation with the Snyk Broker. Once provisioned, the token can be used to initialize a new broker client before using the switch API to update the token in use by the integration.

The new provisional token will fail to be created if the integration, or any other integration in the same group, already has one provisioned.

Required permissions

• View Organization

• View Integrations

• Edit Integrations

POSThttps://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication/provision-token

Path parameters

orgId*string

The API_KEY must have access to this organization.

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

integrationId*string

Example: "4a18d42f-0706-4ad0-b127-24078731fbed"

Header parameters

Response

200

Body

application/json; charset=utf-8

id*string

provisionalBrokerToken*string

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/integrations/{integrationId}/authentication/provision-token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Response

200

{
  "id": "9a3e5d90-b782-468a-a042-9a2073736f0b",
  "provisionalBrokerToken": "4a18d42f-0706-4ad0-b127-24078731fbed"
}