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

get

/orgs

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.snyk.io/v1/orgs' \
  --header 'Content-Type: application/json; charset=utf-8'

200

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.

post

/org

Body

namestringrequired

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

Example: {"name":"new-org","groupId":"4a18d42f-0706-4ad0-b127-24078731fbed","sourceOrgId":"6b4a3261-b68f-43a0-9218-1f082e77f879"}

Responses

application/json; charset=utf-8

application/json, charset=utf-8

application/json, charset=utf-8

application/json, charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.snyk.io/v1/org' \
  --header 'Content-Type: application/json' \
  --data '{"name":"new-org","groupId":"4a18d42f-0706-4ad0-b127-24078731fbed","sourceOrgId":"6b4a3261-b68f-43a0-9218-1f082e77f879"}'

201

400

401

422

201

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

delete

/org/{orgId}

Path parameters

orgIdstringrequired

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

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.snyk.io/v1/org/{orgId}' \
  --header 'Content-Type: application/json; charset=utf-8'

204

204

No body

Update organization settings

Settings that are not provided will not be modified.

Required permissions

• View Organization

• Edit Organization

put

/org/{orgId}/settings

Path parameters

orgIdstringrequired

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

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

Body

string

Example: + Attributes (Org settings request)

Responses

application/json; charset=utf-8

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.snyk.io/v1/org/{orgId}/settings' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '"+ Attributes (Org settings request)"'

200

403

200

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

View organization settings

Required permissions

• View Organization

get

/org/{orgId}/settings

Path parameters

orgIdstringrequired

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

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

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.snyk.io/v1/org/{orgId}/settings' \
  --header 'Content-Type: application/json; charset=utf-8'

200

200

{
  "requestAccess": {
    "enabled": true
  },
  "ignores": {
    "reasonRequired": false,
    "autoApproveIgnores": false
  }
}

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

post

/org/{orgId}/provision

Path parameters

orgIdstringrequired

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

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

Body

string

Example: + Attributes (object) + email (string, required) - The email of the user. + rolePublicId (string) - ID of the role to grant this user. + 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.

Responses

application/json; charset=utf-8

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.snyk.io/v1/org/{orgId}/provision' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '"+ 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."'

200

403

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

get

/org/{orgId}/provision

Path parameters

orgIdstringrequired

The organization ID.

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

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.snyk.io/v1/org/{orgId}/provision' \
  --header 'Content-Type: application/json; charset=utf-8'

200

403

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

delete

/org/{orgId}/provision

Path parameters

orgIdstringrequired

The organization ID.

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

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.snyk.io/v1/org/{orgId}/provision' \
  --header 'Content-Type: application/json; charset=utf-8'

200

403

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

put

/org/{orgId}/notification-settings

Path parameters

orgIdstringrequired

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

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

Body

new-issues-remediationsNewissuesnotificationsettingrequest

project-importedSimplenotificationsettingrequest

test-limitSimplenotificationsettingrequest

weekly-reportSimplenotificationsettingrequest

any

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

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.snyk.io/v1/org/{orgId}/notification-settings' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{"new-issues-remediations":{"enabled":true,"issueSeverity":"high","issueType":"vuln"},"project-imported":{"enabled":true},"test-limit":{"enabled":true},"weekly-report":{"enabled":true}}'

200

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

get

/org/{orgId}/notification-settings

Path parameters

orgIdstringrequired

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

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

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.snyk.io/v1/org/{orgId}/notification-settings' \
  --header 'Content-Type: application/json; charset=utf-8'

200

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

get

/org/{orgId}/members

Path parameters

orgIdstringrequired

The organization ID.

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

Query parameters

includeGroupAdminsboolean

Include group administrators who also have access to this organization.

Example: true

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

application/json; charset=utf-8

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.snyk.io/v1/org/{orgId}/members' \
  --header 'Content-Type: application/json; charset=utf-8'

200

200

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

Update a member in the organization

Manage member's roles in your organization

Required permissions

• Manage Users

put

/org/{orgId}/members/{userId}

Path parameters

orgIdstringrequired

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

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

userIdstringrequired

The user ID.

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

Body

rolestring

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

any

Example: {"role":""}

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.snyk.io/v1/org/{orgId}/members/{userId}' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{"role":""}'

200

200

No body

Remove a member from the organization

Manage member's roles in your organization

Required permissions

• View Organization

• View Users

• User Remove

delete

/org/{orgId}/members/{userId}

Path parameters

orgIdstringrequired

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

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

userIdstringrequired

The user ID we want to remove.

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

Header parameters

Content-Typestring · enumrequired

Example: application/json; charset=utf-8

Options: application/json; charset=utf-8

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.snyk.io/v1/org/{orgId}/members/{userId}' \
  --header 'Content-Type: application/json; charset=utf-8'

200

200

No body

Update a member's role in the organization

Update member's role in your organization by role publicId

Required permissions

• Manage Users

put

/org/{orgId}/members/update/{userId}

Path parameters

orgIdstringrequired

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

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

userIdstringrequired

The user ID.

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

Body

rolePublicIdstring

The new role public ID to update the user to.

any

Example: {"rolePublicId":""}

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.snyk.io/v1/org/{orgId}/members/update/{userId}' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{"rolePublicId":""}'

200

200

No body

Invite users

Invite users to the organization by email

Required permissions

• View Organization

• View Users

• Invite Users

post

/org/{orgId}/invite

Path parameters

orgIdstringrequired

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

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

Body

emailstring

The email of the user.

isAdminboolean

(optional) Set the role as admin.

any

Example: {"email":""}

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.snyk.io/v1/org/{orgId}/invite' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{"email":""}'

200

200

No body