Organizations (v1)

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

List all the organizations a user belongs to

Each request to Snyk has to be done in the context of a Snyk organization. If no organization is specified, the user's default organization (user is identified according to the API_KEY) will be used. The organization determines the access rights, licenses policy and is the unit of billing for private projects.

An organization should be given as a query parameter named org, with the public identifier given to this org. The list of organizations and their corresponding public ids can be found with the organization resource

Required permissions

• View Organization

GEThttps://api.snyk.io/v1/orgs

Header parameters

Response

200

Body

application/json; charset=utf-8

orgs*array of Orgs2

Request

JavaScriptCurlPython

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

Response

200

{
  "orgs": [
    {
      "name": "text",
      "id": "text",
      "slug": "text",
      "url": "text",
      "group": {}
    }
  ]
}

Create a new organization

An organization can be created as part of a group, or independently. If the groupId is not provided, a Personal Org will be created independent of a group.

POSThttps://api.snyk.io/v1/org

Body

application/json

name*string

The name of the new organization

Example: "new-org"

groupIdstring

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

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

sourceOrgIdstring

The id of an organization to copy settings from.

If provided, this organization must be associated with the same group.

The items that will be copied are: Source control integrations (GitHub, GitLab, BitBucket) + Container registries integrations (ACR, Docker Hub, ECR, GCR) + Container orchestrators integrations (Kubernetes) + PaaS and Serverless Integrations (Heroku, AWS Lambda) + Notification integrations (Slack, Jira) + Policies + Ignore settings + Language settings + Infrastructure as Code settings + Snyk Code settings

The following will not be copied across: Service accounts + Members + Projects + Notification preferences

Example: "6b4a3261-b68f-43a0-9218-1f082e77f879"

any

Response

201400401422

Body

application/json; charset=utf-8

id*string

name*string

slug*string

url*string

created*string

group*Group1

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "new-org",
      "groupId": "4a18d42f-0706-4ad0-b127-24078731fbed",
      "sourceOrgId": "6b4a3261-b68f-43a0-9218-1f082e77f879"
    }),
});
const data = await response.json();

Response

201400401422

{
  "id": "0356f641-c55c-488f-af05-c2122590f369",
  "name": "new-org",
  "slug": "new-org",
  "url": "https://api.snyk.io/v1/org/new-org",
  "created": "2021-01-07T16:07:16.237Z",
  "group": {
    "name": "test-group",
    "id": "4a18d42f-0706-4ad0-b127-24078731fbed"
  }
}

Remove organization

Required permissions

• View Organization

• Remove Organization

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

Path parameters

orgId*string

The organization ID. The API_KEY must have permission to delete the provided organization. Currently this operation is only supported for organizations without any projects.

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

Header parameters

Response

204

Request

JavaScriptCurlPython

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

Update organization settings

Settings that are not provided will not be modified.

Required permissions

• View Organization

• Edit Organization

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

Path parameters

orgId*string

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

Example: "25065eb1-109c-4c3e-9503-68fc56ef6f44"

Body

application/json; charset=utf-8

string

Example: "+ Attributes (Org settings request)"

Response

200403

Body

application/json; charset=utf-8

requestAccessall of

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/settings', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify("+ Attributes (Org settings request)"),
});
const data = await response.json();

Response

200

{
  "requestAccess": {
    "enabled": true
  }
}

View organization settings

Required permissions

• View Organization

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

Path parameters

orgId*string

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

Example: "25065eb1-109c-4c3e-9503-68fc56ef6f44"

Header parameters

Response

200

Body

application/json; charset=utf-8

requestAccessall of

any

Request

JavaScriptCurlPython

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

Response

200

{
  "requestAccess": {
    "enabled": true
  }
}

Provision a user to the organization

This endpoint allows Snyk Admins to provision user access to Snyk Orgs prior to the user login to the Snyk platform, and does not send out invitation emails to the Snyk platform. When the provisioned user logs into Snyk for the first time, the user will automatically be granted the appropriate Snyk org access and role permissions specified in the API call. This endpoint can be called multiple times to provision a user to multiple Snyk orgs. The API token used requires Org Admin permisisons, and must be part of a Snyk group with a valid SSO connection. Service accounts are restricted from invoking this API. As this endpoint can only be used to provision new users, if a user has already logged into Snyk, this endpoint will not work to provision user access

Required permissions

• Provision User

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

Path parameters

orgId*string

The organization ID. The API_KEY must not exceed the permissions being granted to the provisioned user.

Example: "25065eb1-109c-4c3e-9503-68fc56ef6f44"

Body

application/json; charset=utf-8

string

Example: "+ Attributes (object)\n + email (string, required) - The email of the user.\n + rolePublicId (string) - ID of the role to grant this user.\n + role (string) - Deprecated. Name of the role to grant this user. Must be one of `ADMIN`, `COLLABORATOR`, or `RESTRICTED_COLLABORATOR`. This field is invalid if `rolePublicId` is supplied with the request."

Response

200403

Body

application/json; charset=utf-8

emailstring

The email of the user.

rolestring

Name of the role granted for this user.

rolePublicIdstring

ID of the role to granted for this user.

createdstring

Timestamp of when this provision record was created.

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/provision', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify("+ Attributes (object)\n    + email (string, required) - The email of the user.\n    + rolePublicId (string) - ID of the role to grant this user.\n    + role (string) - Deprecated. Name of the role to grant this user. Must be one of `ADMIN`, `COLLABORATOR`, or `RESTRICTED_COLLABORATOR`. This field is invalid if `rolePublicId` is supplied with the request."),
});
const data = await response.json();

Response

200

{
  "email": "",
  "role": "",
  "rolePublicId": "",
  "created": ""
}

List pending user provisions

This endpoint allows Snyk Admins to provision user access to Snyk Orgs prior to the user login to the Snyk platform, and does not send out invitation emails to the Snyk platform. When the provisioned user logs into Snyk for the first time, the user will automatically be granted the appropriate Snyk org access and role permissions specified in the API call. This endpoint can be called multiple times to provision a user to multiple Snyk orgs. The API token used requires Org Admin permisisons, and must be part of a Snyk group with a valid SSO connection. Service accounts are restricted from invoking this API. As this endpoint can only be used to provision new users, if a user has already logged into Snyk, this endpoint will not work to provision user access

Required permissions

• Provision User

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

Path parameters

orgId*string

The organization ID.

Example: "25065eb1-109c-4c3e-9503-68fc56ef6f44"

Header parameters

Response

200403

Body

application/json; charset=utf-8

emailstring

The email of the user.

rolestring

Name of the role granted for this user.

rolePublicIdstring

ID of the role to granted for this user.

createdstring

Timestamp of when this provision record was created.

Request

JavaScriptCurlPython

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

Response

200

[
  {
    "email": "",
    "role": "",
    "rolePublicId": "",
    "created": ""
  }
]

Delete pending user provision

This endpoint allows Snyk Admins to provision user access to Snyk Orgs prior to the user login to the Snyk platform, and does not send out invitation emails to the Snyk platform. When the provisioned user logs into Snyk for the first time, the user will automatically be granted the appropriate Snyk org access and role permissions specified in the API call. This endpoint can be called multiple times to provision a user to multiple Snyk orgs. The API token used requires Org Admin permisisons, and must be part of a Snyk group with a valid SSO connection. Service accounts are restricted from invoking this API. As this endpoint can only be used to provision new users, if a user has already logged into Snyk, this endpoint will not work to provision user access

Required permissions

• Provision User

DELETEhttps://api.snyk.io/v1/org/{orgId}/provision

Path parameters

orgId*string

The organization ID.

Example: "25065eb1-109c-4c3e-9503-68fc56ef6f44"

Header parameters

Response

200403

Body

application/json; charset=utf-8

okboolean

Deletion succeeded.

any

Request

JavaScriptCurlPython

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

Response

200

{
  "ok": false
}

Set notification settings

Manage the default settings for organization notifications. These will be used as defaults, but can be re-defined by organization members

Required permissions

• View Organization

• Edit Organization

PUThttps://api.snyk.io/v1/org/{orgId}/notification-settings

Path parameters

orgId*string

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

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

Body

application/json; charset=utf-8

new-issues-remediationsNewissuesnotificationsettingrequest

project-importedSimplenotificationsettingrequest

test-limitSimplenotificationsettingrequest

weekly-reportSimplenotificationsettingrequest

any

Response

200

Body

application/json; charset=utf-8

new-issues-remediationsNotificationsettingresponse

project-importedSimplenotificationsettingresponse

test-limitSimplenotificationsettingresponse

weekly-reportSimplenotificationsettingresponse

any

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/notification-settings', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "new-issues-remediations": {
        "enabled": true,
        "issueSeverity": "high",
        "issueType": "vuln"
      },
      "project-imported": {
        "enabled": true
      },
      "test-limit": {
        "enabled": true
      },
      "weekly-report": {
        "enabled": true
      }
    }),
});
const data = await response.json();

Response

200

{
  "new-issues-remediations": {
    "enabled": true,
    "issueSeverity": "high",
    "issueType": "vuln",
    "inherited": false
  },
  "project-imported": {
    "enabled": true,
    "inherited": false
  },
  "test-limit": {
    "enabled": true,
    "inherited": false
  },
  "weekly-report": {
    "enabled": true,
    "inherited": false
  }
}

Get organization notification settings

Manage the default settings for organization notifications. These will be used as defaults, but can be re-defined by organization members

Required permissions

• View Organization

GEThttps://api.snyk.io/v1/org/{orgId}/notification-settings

Path parameters

orgId*string

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

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

Header parameters

Response

200

Body

application/json; charset=utf-8

new-issues-remediationsNotificationsettingresponse

project-importedSimplenotificationsettingresponse

test-limitSimplenotificationsettingresponse

weekly-reportSimplenotificationsettingresponse

any

Request

JavaScriptCurlPython

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

Response

200

{
  "new-issues-remediations": {
    "enabled": true,
    "issueSeverity": "high",
    "issueType": "vuln",
    "inherited": false
  },
  "project-imported": {
    "enabled": true,
    "inherited": false
  },
  "test-limit": {
    "enabled": true,
    "inherited": false
  },
  "weekly-report": {
    "enabled": true,
    "inherited": false
  }
}

List Members

Manage members in your organization

Required permissions

• View Organization

• View Users

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

Path parameters

orgId*string

The organization ID.

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

Query parameters

Header parameters

Response

200

Body

application/json; charset=utf-8

idstring

The id of the user.

namestring

The name of the user.

usernamestring

The username of the user.

emailstring

The email of the user.

rolestring

The role of the user in the organization.

Request

JavaScriptCurlPython

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

Response

200

[
  {
    "id": "",
    "name": "",
    "username": "",
    "email": "",
    "role": ""
  }
]

Update a member in the organization

Manage member's roles in your organization

Required permissions

• Manage Users

PUThttps://api.snyk.io/v1/org/{orgId}/members/{userId}

Path parameters

orgId*string

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

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

userId*string

The user ID.

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

Body

application/json; charset=utf-8

rolestring

The new role of the user, "admin" or "collaborator".

any

Response

200

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/members/{userId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "role": ""
    }),
});
const data = await response.json();

Remove a member from the organization

Manage member's roles in your organization

Required permissions

• View Organization

• View Users

• User Remove

DELETEhttps://api.snyk.io/v1/org/{orgId}/members/{userId}

Path parameters

orgId*string

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

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

userId*string

The user ID we want to remove.

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

Header parameters

Response

200

Request

JavaScriptCurlPython

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

Update a member's role in the organization

Update member's role in your organization by role publicId

Required permissions

• Manage Users

PUThttps://api.snyk.io/v1/org/{orgId}/members/update/{userId}

Path parameters

orgId*string

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

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

userId*string

The user ID.

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

Body

application/json; charset=utf-8

rolePublicIdstring

The new role public ID to update the user to.

any

Response

200

Request

JavaScriptCurlPython

const response = await fetch('https://api.snyk.io/v1/org/{orgId}/members/update/{userId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify({
      "rolePublicId": ""
    }),
});
const data = await response.json();

Invite users

Invite users to the organization by email

Required permissions

• View Organization

• View Users

• Invite Users

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

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

emailstring

The email of the user.

isAdminboolean

(optional) Set the role as admin.

any

Response

200

Request

JavaScriptCurlPython

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