What is changing?
In addition to the Updated URI for project avatars announcement, we’re updating the way in which avatars, attachments, and attachment thumbnails are referenced in response objects. These items will be represented by URIs for the appropriate REST API operation, rather than using non-REST URIs. These changes are to ensure that the appropriate OAuth scope checks are made when these objects are requested.
We’ve updated the following resources:
Avatar URIs
The secure/viewavatar
and secure/projectavatar
endpoints, which would return an avatar image matching the provided avatar ID and type, will now refer to the Get avatar image by ID API. This API requires the read:jira-work
OAuth scope.
Before
{
"self": "https://your-domain.atlassian.net/rest/api/3/issue/10000",
"key": "MY-1",
"fields": {
"issuetype": {
"name": "My issue type",
"iconUrl": "https://your-domain.atlassian.net/secure/viewavatar?size=medium&avatarId=10100&avatarType=issuetype"
},
"project": {
"name": "My project",
"avatarUrls": {
"48x48": "https://your-domain.atlassian.net/secure/projectavatar?pid=10000&avatarId=10200"
}
}
}
}
After
{
"self": "https://your-domain.atlassian.net/rest/api/3/issue/10000",
"key": "MY-1",
"fields": {
"issuetype": {
"name": "My issue type",
"iconUrl": "https://your-domain.atlassian.net/rest/api/3/universal_avatar/view/type/issuetype/avatar/10100"
},
"project": {
"name": "My project",
"avatarUrls": {
"48x48": "https://your-domain.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10200"
}
}
}
}
Affected operations
The following operations referencing the secure/viewavatar
resource are affected by this change:
-
Get issue link - GET
/rest/api/3/issueLink/{linkId}
-
Get all issue types for user - GET
/rest/api/3/issuetype
-
Get issue types for project - GET
/rest/api/3/issuetype/project
-
Get issue type - GET
/rest/api/3/issuetype/{id}
-
Get alternative issue types - GET
/rest/api/3/issuetype/{id}/alternatives
-
Get project - GET
/rest/api/3/project/{projectIdOrKey}
-
Update project - PUT
/rest/api/3/project/{projectIdOrKey}
-
Get all project avatars - GET
/rest/api/3/project/{projectIdOrKey}/avatars
-
Restore deleted project - POST
/rest/api/3/project/{projectIdOrKey}/restore
-
Update project type - PUT
/rest/api/3/project/{projectIdOrKey}/type/{newProjectTypeKey}
-
Get avatars - GET
/rest/api/3/universal_avatar/type/{type}/owner/{entityId}
The following operations referencing the secure/projectavatar
resource are affected by this change:
-
Get favorite filters - GET
/rest/api/3/filter/favourite
-
Get my filters - GET
/rest/api/3/filter/my
-
Search for filters - GET
/rest/api/3/filter/search
-
Get share permissions - GET
/rest/api/3/filter/{id}/permission
-
Add share permission - POST
/rest/api/3/filter/{id}/permission
-
Get create issue metadata - GET
/rest/api/3/issue/createmeta
-
Get issue - GET
/rest/api/3/issue/{issueIdOrKey}
-
Get issue type screen scheme projects - GET
/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}/project
-
Get all projects - GET
/rest/api/3/project
-
Get recent projects - GET
/rest/api/3/project/recent
-
Get projects paginated - GET
/rest/api/3/project/search
-
Get project - GET
/rest/api/3/project/{projectIdOrKey}
-
Update project - PUT
/rest/api/3/project/{projectIdOrKey}
-
Restore deleted project - POST
/rest/api/3/project/{projectIdOrKey}/restore
-
Update project type - PUT
/rest/api/3/project/{projectIdOrKey}/type/{newProjectTypeKey}
-
Search for issues using JQL (GET) - GET
/rest/api/3/search
-
Search for issues using JQL (POST) - POST
/rest/api/3/search
Get attachment and thumbnail
Responses that include an attachment URI will now refer to the Get attachment content API. This API requires the read:jira-work
OAuth scope.
Responses that include a thumbnail URI will now refer to the Get attachment thumbnail API. This API requires the read:jira-work
OAuth scope.
Additionally, there are resources which currently return a prefixed URI used by Jira Service Management, e.g. /servicedesk/customershim/secure/attachment/*
and /servicedesk/customershim/secure/thumbnail/*
. These will also be transitioned to a new REST API which will be referenced here once the API has been finalised.
Before
{
"id": 10000,
"self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
"filename": "picture.jpg",
"content": "https://your-domain.atlassian.net/jira/secure/attachments/10000/picture.jpg",
"thumbnail": "https://your-domain.atlassian.net/jira/secure/thumbnail/10000/picture.jpg"
}
After
{
"id": 10000,
"self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
"filename": "picture.jpg",
"content": "https://your-domain.atlassian.net/rest/api/3/attachment/content/10000",
"thumbnail": "https://your-domain.atlassian.net/rest/api/3/attachment/thumbnail/10000"
}
Affected operations
The following operations referencing the secure/attachments
and secure/thumbnail
resources are affected by this change:
-
Get attachment metadata - GET
/rest/api/3/attachment/{id}
-
Get issue - GET
/rest/api/3/issue/{issueIdOrKey}
-
Search for issues using JQL (GET) - GET
/rest/api/3/search
-
Search for issues using JQL (POST) - POST
/rest/api/3/search
)
Why is it changing?
OAuth scopes were not being correctly enforced for app developers who were following the above resources in REST responses. Additionally there was no clear documentation available for developers who wish to consume these APIs.
What do I need to do?
If you are a developer who is following links in REST responses to request one of the above APIs, you’ll need to ensure you have declared the appropriate OAuth scope in your app descriptor. Otherwise a 403
error will be returned attempting to request the resource.
By when do I need to do it?
Changes will begin rolling out to the Jira ecosystem beta group from November 9, 2021.
These resources will be rolled out independently and we expect all APIs to reach 100% of production instances by January 14, 2022.