Atlassian Jira Issue Security Schemes API
The Atlassian Jira Issue Security Schemes API enables managing security schemes that control which users can view specific issues.
OpenAPI Specification
components:
schemas:
PageBeanSecurityLevel:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/SecurityLevel'
readOnly: true
type: array
type: object
PageBeanSecurityLevelMember:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/SecurityLevelMember'
readOnly: true
type: array
type: object
PageBeanIssueSecuritySchemeToProjectMapping:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/IssueSecuritySchemeToProjectMapping'
readOnly: true
type: array
type: object
PageBeanSecuritySchemeWithProjects:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/SecuritySchemeWithProjects'
readOnly: true
type: array
type: object
SecurityScheme:
additionalProperties: false
description: Details about a security scheme.
properties:
defaultSecurityLevelId:
description: The ID of the default security level.
format: int64
readOnly: true
type: integer
description:
description: The description of the issue security scheme.
readOnly: true
type: string
id:
description: The ID of the issue security scheme.
format: int64
readOnly: true
type: integer
levels:
items:
$ref: '#/components/schemas/SecurityLevel'
type: array
name:
description: The name of the issue security scheme.
readOnly: true
type: string
self:
description: The URL of the issue security scheme.
readOnly: true
type: string
type: object
PageBeanIssueSecurityLevelMember:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/IssueSecurityLevelMember'
readOnly: true
type: array
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/issuesecurityschemes/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/issuesecurityschemes/level:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of issue security
levels.<br><br>Only issue security levels in the context of classic
projects are returned.<br><br>Filtering using IDs is inclusive: if you
specify both security scheme IDs and level IDs, the result will include
both specified issue security levels and all issue security levels from
the specified schemes.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetsecuritylevels
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: '0'
type: string
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: '50'
type: string
- description: >-
The list of issue security scheme level IDs. To include multiple
issue security levels, separate IDs with an ampersand:
`id=10000&id=10001`.
in: query
name: id
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
The list of issue security scheme IDs. To include multiple issue
security schemes, separate IDs with an ampersand:
`schemeId=10000&schemeId=10001`.
in: query
name: schemeId
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
When set to true, returns multiple default levels for each security
scheme containing a default. If you provide scheme and level IDs not
associated with the default, returns an empty page. The default
value is false.
in: query
name: onlyDefault
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":50,"startAt":0,"total":1,"values":[{"description":"Only
the reporter and internal staff can see this
issue.","id":"10021","isDefault":true,"issueSecuritySchemeId":"10001","name":"Reporter
Only","self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityscheme/level?id=10021"}]}
schema:
$ref: '#/components/schemas/PageBeanSecurityLevel'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["-1000 is not a valid value. id must be zero
or a positive integer."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Issue Security Levels
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:issue-security-level:jira
- read:issue-security-scheme:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/level/default:
put:
deprecated: false
description: >-
Sets default issue security levels for
schemes.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianSetdefaultlevels
parameters: []
requestBody:
content:
application/json:
example:
defaultValues:
- defaultLevelId: '20000'
issueSecuritySchemeId: '10000'
- defaultLevelId: '30000'
issueSecuritySchemeId: '12000'
schema:
$ref: '#/components/schemas/SetDefaultLevelsRequest'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["some-wrong-string is not a valid value. The
issue security scheme ID must be a positive
integer."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Issue security scheme with ID 10000 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the issue resolution isn't found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Set Default Issue Security Levels
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/level/member:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of issue security level
members.<br><br>Only issue security level members in the context of
classic projects are returned.<br><br>Filtering using parameters is
inclusive: if you specify both security scheme IDs and level IDs, the
result will include all issue security level members from the specified
schemes and levels.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetsecuritylevelmembers
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: '0'
type: string
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: '50'
type: string
- description: >-
The list of issue security level member IDs. To include multiple
issue security level members separate IDs with an ampersand:
`id=10000&id=10001`.
in: query
name: id
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
The list of issue security scheme IDs. To include multiple issue
security schemes separate IDs with an ampersand:
`schemeId=10000&schemeId=10001`.
in: query
name: schemeId
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
The list of issue security level IDs. To include multiple issue
security levels separate IDs with an ampersand:
`levelId=10000&levelId=10001`.
in: query
name: levelId
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Expand options include:
* `all` Returns all expandable information
* `field` Returns information about the custom field granted the permission
* `group` Returns information about the group that is granted the permission
* `projectRole` Returns information about the project role granted the permission
* `user` Returns information about the user who is granted the permission
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"startAt":0,"total":3,"values":[{"id":"10000","issueSecurityLevelId":"20010","issueSecuritySchemeId":"10010","holder":{"expand":"group","type":"group"}}]}
schema:
$ref: '#/components/schemas/PageBeanSecurityLevelMember'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
description: Returned if the user doesn't have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Issue Security Level Members
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:issue-security-level:jira
- read:issue-security-scheme:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/project:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) mapping of projects that are using
security schemes. You can provide either one or multiple security scheme
IDs or project IDs to filter by. If you don't provide any, this will
return a list of all mappings. Only issue security schemes in the
context of classic projects are supported. **[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianSearchprojectsusingsecurityschemes
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: '0'
type: string
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: '50'
type: string
- description: The list of security scheme IDs to be filtered out.
in: query
name: issueSecuritySchemeId
schema:
items:
type: string
type: array
uniqueItems: true
- description: The list of project IDs to be filtered out.
in: query
name: projectId
schema:
items:
type: string
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: '{"issueSecuritySchemeId":"10000","projectId":"10000"}'
schema:
$ref: >-
#/components/schemas/PageBeanIssueSecuritySchemeToProjectMapping
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the search criteria is invalid.If you specify the
project ID parameter
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Projects Using Issue Security Schemes
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-experimental: true
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Associates an issue security scheme with a project and remaps security
levels of issues to the new levels, if provided.<br><br>This operation
is [asynchronous](#async). Follow the `location` link in the response to
determine the status of the task and use [Get
task](#api-rest-api-3-task-taskId-get) to obtain subsequent
updates.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAssociateschemestoprojects
parameters: []
requestBody:
content:
application/json:
example:
oldToNewSecurityLevelMappings:
- newLevelId: '30001'
oldLevelId: '30000'
projectId: '10000'
schemeId: '20000'
schema:
$ref: '#/components/schemas/AssociateSecuritySchemeWithProjectDetails'
required: true
responses:
'303':
content:
application/json:
schema:
$ref: '#/components/schemas/TaskProgressBeanObject'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["some-wrong-string is not a valid value. The
issue security scheme ID must be a positive
integer."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Issue security scheme with ID 10000 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the security scheme isn't found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if a task to remove the issue security level is already
running.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Associate Security Scheme To Project
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/search:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of issue security schemes. <br>If you specify the project ID parameter, the result will contain
issue security schemes and related project IDs you filter by. Use
\{@link
IssueSecuritySchemeResource\#searchProjectsUsingSecuritySchemes(String,
String, Set, Set)\} to obtain all projects related to
scheme.<br><br>Only issue security schemes in the context of classic
projects are returned.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianSearchsecurityschemes
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: '0'
type: string
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: '50'
type: string
- description: >-
The list of issue security scheme IDs. To include multiple issue
security scheme IDs, separate IDs with an ampersand:
`id=10000&id=10001`.
in: query
name: id
schema:
items:
type: string
type: array
uniqueItems: true
- description: >-
The list of project IDs. To include multiple project IDs, separate
IDs with an ampersand: `projectId=10000&projectId=10001`.
in: query
name: projectId
schema:
items:
type: string
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityscheme/10000","name":"Default
scheme","description":"Default scheme
description","defaultLevel":10001,"projectIds":[10002]}
schema:
$ref: '#/components/schemas/PageBeanSecuritySchemeWithProjects'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["-1000 is not a valid value. id must be zero
or a positive integer."],"errors":{}}
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
description: Returned if the user doesn't have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Search Issue Security Schemes
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:issue-security-level:jira
- read:issue-security-scheme:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/{id}:
get:
deprecated: false
description: >-
Returns an issue security scheme along with its security
levels.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).<br> * *Administer Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for a project
that uses the requested issue security scheme.
operationId: atlassianGetissuesecurityscheme
parameters:
- description: >-
The ID of the issue security scheme. Use the [Get issue security
schemes](#api-rest-api-3-issuesecurityschemes-get) operation to get
a list of issue security scheme IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
example: >-
{"defaultSecurityLevelId":10021,"description":"Description for
the default issue security
scheme","id":10000,"levels":[{"description":"Only the reporter
and internal staff can see this
issue.","id":"10021","name":"Reporter
Only","self":"https://your-domain.atlassian.net/rest/api/3/securitylevel/10021"}],"name":"Default
Issue Security
Scheme","self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityschemes/10000"}
schema:
$ref: '#/components/schemas/SecurityScheme'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have the administrator permission and
the scheme is not used in any project where the user has
administrative permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
summary: Atlassian Get Issue Security Scheme
tags:
- Issue Security Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:issue-security-level:jira
- read:issue-security-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates the issue security scheme.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdateissuesecurityscheme
parameters:
- description: The ID of the issue security scheme.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
descrip
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-issuesecurityschemes--openapi-original.yml