The Jira Software Cloud REST API

Security Information

APIs related to integrating Security information with Jira Software. These APIs are available to Atlassian Connect apps. To use these APIs you must have the Security module in your app's descriptor. Read more about Jira Software modules here.

Submit Security Workspaces to link

POST /rest/security/1.0/linkedWorkspaces/bulk

Insert Security Workspace IDs to establish a relationship between them and the Jira site the app is installed on. If a relationship between the workspace ID and Jira already exists then the workspace ID will be ignored and Jira will process the rest of the entries.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'WRITE' scope for Connect apps.

Connect app scope required: WRITE

Request

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define the Security Information module it will be rejected with a 403.

Read understanding jwt for more details.

Pattern: JWT \S+

Body parameters

The payload used to submit (update / insert) Security Workspace IDs.

workspaceIds Required

Array<string>

The IDs of Security Workspaces to link to this Jira site.

Min items: 1, Max items: 100

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/linkedWorkspaces/bulk' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceIds": [
    "111-222-333",
    "444-555-666"
  ]
}'

Responses

202

400

401

403

413

429

503

default

Submission accepted. Each submitted Security Workspace ID will be linked to Jira.

A schema has not been defined for this response code.

Delete linked Security Workpaces

DELETE /rest/security/1.0/linkedWorkspaces/bulk

Bulk delete all linked Security Workspaces that match the given request.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.

e.g. DELETE /bulk?workspaceIds=111-222-333,444-555-666

Connect app scope required: DELETE

Request

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define the Security Information module it will be rejected with a 403.

Read understanding jwt for more details.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/linkedWorkspaces/bulk'

Responses

202

400

401

403

429

503

default

Delete accepted. Workspaces and related data will eventually be removed from Jira.

A schema has not been defined for this response code.

Get linked Security Workspaces

GET /rest/security/1.0/linkedWorkspaces

Retrieve all Security Workspaces linked with the Jira site.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.

Connect app scope required: READ

Request

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define the Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/linkedWorkspaces' \
  --header 'Accept: application/json'

Responses

200

401

403

404

429

503

default

A list of all stored workspace IDs.

Content type	Value
application/json	SecurityWorkspaceIds

Get a linked Security Workspace by ID

GET /rest/security/1.0/linkedWorkspaces/{workspaceId}

Retrieve a specific Security Workspace linked to the Jira site for the given workspace ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.

Connect app scope required: READ

Request

Path parameters

workspaceId Required

string

The ID of the workspace to fetch.

Max length: 255

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define the Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/linkedWorkspaces/{workspaceId}' \
  --header 'Accept: application/json'

Responses

200

401

403

404

429

503

default

The Security Workspace information stored for the given ID.

Content type	Value
application/json	SecurityWorkspaceResponse

Submit Vulnerability data

POST /rest/security/1.0/bulk

Update / Insert Vulnerability data.

Vulnerabilities are identified by their ID, any existing Vulnerability data with the same ID will be replaced if it exists and the updateSequenceNumber of the existing data is less than the incoming data.

Submissions are performed asynchronously. Most updates are available within a short period of time but may take some time during peak load and/or maintenance times. The GET vulnerability endpoint can be used to confirm that data has been stored successfully (if needed).

In the case of multiple Vulnerabilities being submitted in one request, each is validated individually prior to submission. Details of Vulnerabilities that failed submission (if any) are available in the response object.

A maximum of 1000 vulnerabilities can be submitted in one request.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'WRITE' scope for Connect apps.

Connect app scope required: WRITE

Request

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define the Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Body parameters

The payload used to submit (update / insert) Vulnerability data.

properties

Properties

Properties assigned to vulnerability data that can then be used for delete / query operations.

Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system.

Properties are supplied as key/value pairs, and a maximum of 5 properties can be supplied, keys cannot contain ':' or start with '_'.

Max properties: 5

vulnerabilities Required

Array<Vulnerability>

Min items: 1, Max items: 1000

providerMetadata

ProviderMetadata

Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. Information in this property is not considered private, so it should not contain personally identifiable information

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/bulk' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "properties": {
    "accountId": "account-234",
    "projectId": "project-123"
  },
  "vulnerabilities": [
    {
      "schemaVersion": "1.0",
      "id": "111-222-333",
      "updateSequenceNumber": 1523494301448,
      "containerId": "111-222-333",
      "displayName": "curl/libcurl3 - Buffer Override",
      "description": "## Overview\n\n\nAffected versions of this package are vulnerable to MeltLeak",
      "url": "https://example.com/project/CWE-123/summary",
      "type": "sca",
      "introducedDate": "2018-01-20T23:27:25.000Z",
      "lastUpdated": "2018-01-20T23:27:25.000Z",
      "severity": {
        "level": "critical"
      },
      "identifiers": [
        {
          "displayName": "CWE-123",
          "url": "https://cwe.mitre.org/data/definitions/123.html"
        }
      ],
      "status": "open",
      "associations": [
        {
          "associationType": "issueKeys",
          "values": [
            "ABC-123",
            "ABC-456"
          ]
        }
      ]
    }
  ],
  "providerMetadata": {
    "product": "Atlassian Security Platform 2.1.0"
  }
}'

Responses

202

400

401

403

413

429

503

default

Submission accepted. Each Vulnerability submitted in a valid format will eventually be available in Jira.

Details of any Vulnerabilities that were submitted but failed submission (due to data format problems, etc.) are available in the response object.

Content type	Value
application/json	SubmitVulnerabilitiesResponse

Delete Vulnerabilities by Property

DELETE /rest/security/1.0/bulkByProperties

Bulk delete all Vulnerabilities that match the given request.

One or more query params must be supplied to specify Properties to delete by. If more than one Property is provided, data will be deleted that matches ALL of the Properties (e.g. treated as an AND). Read the POST bulk endpoint documentation for more details.

e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456

Deletion is performed asynchronously. The GET vulnerability endpoint can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.

Connect app scope required: DELETE

Request

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/bulkByProperties'

Responses

202

400

401

403

429

503

default

Delete accepted. Data will eventually be removed from Jira.

A schema has not been defined for this response code.

Get a Vulnerability by ID

GET /rest/security/1.0/vulnerability/{vulnerabilityId}

Retrieve the currently stored Vulnerability data for the given ID.

The result will be what is currently stored, ignoring any pending updates or deletes.

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'READ' scope for Connect apps.

Connect app scope required: READ

Request

Path parameters

vulnerabilityId Required

string

The ID of the Vulnerability to fetch.

Max length: 255

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/vulnerability/{vulnerabilityId}' \
  --header 'Accept: application/json'

Responses

200

401

403

404

429

503

default

The Vulnerability data currently stored for the given ID.

Content type	Value
application/json	object

Delete a Vulnerability by ID

DELETE /rest/security/1.0/vulnerability/{vulnerabilityId}

Delete the Vulnerability data currently stored for the given ID.

Deletion is performed asynchronously. The GET vulnerability endpoint can be used to confirm that data has been deleted successfully (if needed).

Only Connect apps that define the jiraSecurityInfoProvider module can access this resource. This resource requires the 'DELETE' scope for Connect apps.

Connect app scope required: DELETE

Request

Path parameters

vulnerabilityId Required

string

The ID of the Vulnerability to delete.

Max length: 255

Header parameters

Authorization Required

string

All requests must be signed with a Connect JWT token that corresponds to the Provider app installed in Jira.

If the JWT token corresponds to an app that does not define Security Information module it will be rejected with a 403.

Read more about JWT here.

Pattern: JWT \S+

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'https://your-domain.atlassian.com/rest/security/1.0/vulnerability/{vulnerabilityId}'

Responses

202

401

403

429

503

default

Delete has been accepted. If the data exists, it will eventually be removed from Jira.

A schema has not been defined for this response code.