OAuth 2.0 (3LO) apps don't have access to restricted email addresses

This post wants to clarify the behaviour around accessing restricted email addresses from OAuth 2.0 (3LO) apps. The explanation applies to both Jira and Confluence Cloud.

Can OAuth 2.0 (3LO) apps access restricted email addresses?
The short answer is no.

If a user decided to restrict the visibility of their email address, a 3LO app can’t access it.

The process for gaining access to the Email API described in the Guidelines for requesting access to email address post only applies to Connect apps.

My OAuth 2.0 (3LO) apps has access to some email addresses. How is that possible?
3LO apps only have access to restricted email addresses in these cases:

  • the request is for the same user (the resource owner) who consented to the app
    – this is what the “2. Apps have received explicit consent from individuals through a 3LO consent flow.” point is referring to in the Guidelines for requesting access to email address post.
  • the email address is for another user (not the one who consented to the app) and the email visibility is set to Anyone

How can an app retrieve an email address?
Keeping in mind that the conditions above apply, 3LO apps can retrieve a user email address in the following way:

  • Using the GET /rest/api/2/user REST API
    – With the accountId parameter matching the user associated to the request bearer token (so the token associated to the user that consented / completed the authentication flow for the app). For the user who contented to the app, the emailAddress field is always returned regardless of the Email address privacy setting. This is equivalent to calling the GET /rest/api/2/myself REST API and is recommended to avoid possible mistakes when using an incorrect parameter.
    – With an accountId for a different user (not the one associated to the token used for the request), only if the email visibility is set to Anyone
  • Using the https://api.atlassian.com/me REST API (documented here), which requires the read:me scope to be granted. * this API returns the email address of the user associated to the token, regardless of the Email address privacy settings. When using this endpoint, the email field in the payload is called mail and not emailAddress.

FAQs
What happens when a 3LO app attempts to retrieve the email address of a different user via the GET /rest/api/2/user REST API?
The response does not contain the emailAdress field.

Is the email REST API available for 3LO apps?
No, the endpoint returns a OAuth 2.0 is not enabled for method: GET /rest/api/2/user/email when the request is from a 3LO app.

Hope this helps,
Caterina

2 Likes