What is changing?
Project avatar URIs that are included in REST API response objects will return an absolute URI referencing new REST APIs for retrieving avatar images. The following APIs have been introduced:
For example, if we compare a project object using the Get projects paginated API.
Old format
{
"id": "10000",
"name": "My Project",
"avatarUrls": {
"48x48": "https://example.atlassian.net/secure/projectavatar?pid=10000&avatarId=10409",
"24x24": "https://example.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10409",
"16x16": "https://example.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10409",
"32x32": "https://example.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10409"
}
}
New format
{
"id": "10000",
"name": "My Project",
"avatarUrls": {
"48x48": "https://example.atlassian.net/rest/api/2/universal_avatar/view/type/project/avatar/10409",
"24x24": "https://example.atlassian.net/rest/api/2/universal_avatar/view/type/project/avatar/10409?size=small",
"16x16": "https://example.atlassian.net/rest/api/2/universal_avatar/view/type/project/avatar/10409?size=xsmall",
"32x32": "https://example.atlassian.net/rest/api/2/universal_avatar/view/type/project/avatar/10409?size=medium"
}
}
Apps will require the read:jira-work OAuth scope in order to access these APIs, and the following permission checks will be enforced:
- For system avatars, none.
- For custom project avatars, Browse projects project permission for the project the avatar belongs to.
- For custom issue type avatars, Browse projects project permission for at least one project the issue type is used in.
Why is it changing?
OAuth scopes were not being correctly enforced for app developers who were following project avatar links in REST responses and there was no clear documentation available for developers who wanted to obtain avatar images.
What do I need to do?
Developers using this API will need to ensure they have declared the read:jira-work OAuth scope in their app descriptor.
By when do I need to do it?
The change will be rolled out to the Jira ecosystem beta group on October 13, 2021 and will be rolled out to 100% of production instances by December 6, 2021.