RFC-14 App Access Rule

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines : keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

  • Publish: 01 Jun 2023
  • Discuss: 15 Jun 2023
  • Resolve: 29 Jun 2023

Hi Developer Community,
If you’ve been joining our Marketplace Roadmap webinars or following Atlassian’s developer blog, you may know that we’re working to bring admins more control when it comes to apps in cloud. One such initiative is a new control for org admins to block cloud app access to certain Jira projects or Confluence spaces. We believe this will help address concerns around “all-or-nothing” app access, and generally improve app migrations and app adoption amongst our more privacy-sensitive customers in cloud.

We are planning to start testing this feature with customers via an early access program (EAP) in the coming quarter, and have shared some details with a small group of partners to better understand how their apps may be impacted. Understanding potential impacts on your app’s behaviour will help us better prepare to support you and your app’s users. With this post we want to ensure we get feedback from a wider audience.

We have included specific questions below where we’d like your feedback on this feature. Please let us know what you think in the comments.


Over the last few years, Atlassian and many Marketplace Partners have invested heavily in improving customer trust in cloud products and apps. However, customers continue to express concerns about how apps handle their data in cloud. Concerns about app data privacy and security can lead customers to drop apps during migration, or reconsider installing new apps in cloud.

One specific concern we hear from customers is that they can’t control the information apps have access to on their site. When an admin installs an app in Confluence or Jira, the app has access to all the spaces and projects on the instance. If a customer has sensitive information in Confluence or Jira that they’d like to protect (ie: financial data, M&A plans, competitively sensitive internal roadmaps, etc), they can only install apps that they feel are secure enough to access this sensitive information.

Proposed Solution

To address this concern, we’re working on a new administrative control that we are referring to as “App Data Access Controls” in our Cloud Public roadmap. To start with, this feature will allow org admins to define a policy to block apps from accessing selected Confluence spaces and/or Jira projects. Customers can enable or disable this control by selecting “block app access” or keep the default “allow app access” in the app access section of their data security policy.

Selecting “block app access” will prevent any apps from accessing the space(s) or project(s) under the policy. These rules can be updated by admins over time, and will be applicable to apps built for Jira and Confluence on Forge, or with Atlassian Connect or OAuth 2.0 (3LO) frameworks.

Later, we plan to introduce additional, more granular options for Atlassian Access subscribers who will be able to restrict access for specific apps from the list of their installed apps.

Ultimately, we expect this feature to increase customer confidence when installing apps in cloud. This should make it easier:

  • for on-premise customers to migrate to cloud and bring their apps with them, and
  • for cloud customers to install more apps

Here are some mock-ups of the new customer experience:

Mock up of a data security policy summary.

Mock up of app blocking options for a subscriber without Atlassian Access.

Mock up of app blocking options for a subscriber with Atlassian Access.

While we are aiming to ensure our APIs handle this feature as gracefully and transparently as possible, we recognise that many apps have been built with the assumption that, once installed on a site, the app has access to all projects and spaces on that site. Hence, apps may need to be updated in order to avoid presenting confusing or broken experiences to users. We are also evaluating implementing new APIs to allow apps to programmatically determine when data access is updated after a customer applies a new policy.

We are currently running customer research to establish what level of notification admins and users expect to see when an app is blocked. For our targeted EAP in Q3 FY23 we plan to mimic the “app uninstall” experience, however showing app block specific messaging to end users.

Note: this feature does not impact app licensing or billing. Apps will continue to be priced based on the number of licensed users for the host product, irrespective of any app data access policies that are applied.

New App Data Access APIs

We are evaluating two mechanisms to allow apps to detect whether their access to certain data has changed:

  1. New product trigger events for Forge apps and webhooks for Atlassian Connect apps to be notified when a policy change causes a space or project to become inaccessible or accessible(e.g. SPACE_RESTRICTED and SPACE_UNRESTRICTED).
  2. New REST APIs accessible to Forge, Atlassian Connect, and OAuth 2.0 (3LO) apps to retrieve a set of opaque identifiers (e.g. numeric identifiers or UUIDs) for inaccessible spaces.

Note that these APIs will likely target spaces or projects - you will not receive individual webhooks or events for objects within restricted spaces or project, or be able to check the permissions of individual objects. This may present challenges if you are storing space-related data without a reference to the space that data originates from.

:question: Are these new APIs sufficient for your apps to be compatible with this app blocking feature? Are they necessary, or could your app operate without them? If either prove to be unnecessary we may deprioritise them.

Impacts to existing APIs and platform features

Below is a list of our plans for how various extensibility features of our cloud developer platforms will handle app blocking. We would greatly appreciate your review and feedback on these proposed changes, and especially any concerns you may have on adverse impacts to your apps.

Impact to REST APIs

  • For REST APIs that return a collection of spaces or projects such as Confluence Cloud APIs and Jira Cloud APIs, any restricted containers will be omitted from API responses.
  • For REST APIs that search across multiple spaces or projects to return a collection of entities (such as pages, comment or issues fields, issue comments), any entities that belong to restricted spaces will be omitted from API responses.
  • REST APIs that return a single space (example) will instead return a 404 response if the space or project exists but is restricted. This response will be identical to the API’s behaviour where the space does not exist.
  • REST APIs that read an entity that resides in a space (such as a page, comment, blog etc) will return a 404 response if the space it belongs to is restricted. This response will also be identical to the API’s behaviour where the space does not exist.
  • REST APIs that modify an entity that resides in a restricted space or project will return a 403 response.
  • An app access block check will also impact API performance for many product APIs. There will be some impact even in cases where the customer does not have active policies applied. We are aiming to minimise the impact, but do not have concrete figures to share at this time. We will know more once we are starting internal testing.
  • In order to minimise the impact on performance, we are also making some trade-offs to consistency. This means that APIs may return inconsistent results for a short period after policy changes occur. For example, a search API may return references to spaces or projects that your app no longer has permission to view for a brief period after a policy is updated.

:question: Will you need to make changes to your apps to adapt to the new API behaviours?
Do you foresee your app’s feature set or user experience be negatively impacted by the above changes?
Are there any specific REST APIs you are particularly concerned about the impact to?
How sensitive is your app to API latency?

Impact to GraphQL APIs

This section only applies to OAuth 2.0 (3LO) apps, as Confluence’s GraphQL APIs are not yet accessible to Atlassian Connect or Forge apps.

  • For queries that return a collection of results, such as findSpaces, any restricted spaces (or pages, blog posts, or comments within a restricted space) will be omitted in the API response.
  • For queries that return a specific item, such as space or blogPost, will return a null response, signifying that the item was not found (or similar) or contained within a restricted space.
  • For mutations that attempt to update a restricted space, or create or update an item within a restricted space, such as createPage, will fail with a 403 error.

:question: Similar to our questions about REST, will you need to make changes to your apps to adapt to the new API behaviours? Are there any specific GraphQL APIs you are particularly concerned about the impact to?

Impact to content properties

Content properties for Atlassian Connect will continue to expose content property values to CQL and JQL, though content from restricted spaces will not be returned to apps performing CQL queries.

:question: Do you have any concerns about a blocked app’s impact to content properties?

Impacts to App Events

All app events (webhooks for Connect, product events for Forge) relating to restricted spaces and projects or entities that are contained within a restricted space or project, will not be sent.

Note: as policies can be updated by customers at any time, app events will only be dispatched whilst a space or project is visible to an app. This means apps may receive an inconsistent set of app events for a particular entity. For example, an app may receive a space_created event without a corresponding space_deleted event, or vice-versa.

For Connect: Webhooks will no longer be emitted for restricted spaces or projects.
For Forge: Product events will not be sent.

:question: Will you need to make changes to your apps to adapt to the new app event behaviours? Do you foresee your app’s feature set or user experience be negatively impacted by the above changes?

Impact to Macros

All Confluence macros that would be displayed within a restricted space will instead display an error message to users indicating that the app has been blocked by a policy in place of the macro. Additionally, macros from blocked apps will not be discoverable in the macro browser within the context of a restricted space.

:question: Do you have any concerns about an app block’s impact on macros?

Impact to other UI modules (web items, web panels, etc.)

All UI modules that would be displayed within the context of a space or project will not appear if the app has been restricted from accessing that space. For Forge this impacts all Forge UI Kit components.

:question: Do you have any concerns about an app block’s impact on other UI modules?

Frequently asked questions

How should apps determine when a space becomes inaccessible or accessible as the result of a policy change?

Use the APIs described in the “New App Data Access APIs” section above.

How should apps treat stored data relating to spaces or projects that become inaccessible as the result of a policy change?

We can not make any specific recommendations to partners about retention of customer data (or data derived from customer data) after additional data controls are applied. App developers must make their own determination based on their app use-cases, the needs of their users, and any related agreements they have established with their customers. Due to the dynamic nature of legislation and regulations relating to how data is handled in different jurisdictions, it is impossible for Atlassian to share specific guidance on this matter. However, we will try to be as transparent as possible as we learn more about customer expectations in this area.

One approach partners may wish to consider is aligning your app data lifecycle for blocked apps to be similar to how you handle app uninstallation.

How should apps handle a space or project becoming accessible as the result of a policy change?

Similar to the question above, we are not able to make specific recommendations, as it will depend on your app and the needs of your users.

However, one approach partners may wish to consider is aligning this experience with how your app behaves after being freshly installed or after a fresh space import.

How should apps handle user experiences that are presented outside of a space or project context, but collate or display space or project data?

While extension points within a space or project are blocked automatically, you should consider the impact of app blocking on user experiences that your app presents outside of spaces or projects. To avoid confusing users, you may wish to align the data presented in these contexts with the spaces or projects that are currently accessible to your app.

This should be mostly automatic if your UI is purely driven by Atlassian product APIs and you are not storing or caching data, as any spaces or projects that are not accessible to your app will be filtered out of API responses. One caveat here is that some combinations of APIs may be only eventually inconsistent, as noted in the Impact to REST APIs section above.

It may not be automatic if you are caching or storing data relating to a space or project that you accessed prior to a policy being applied. In these cases, you may wish to avoid displaying this data to users to avoid giving the mistaken impression that your app is still accessing restricted spaces or projects.

My app interoperates with other Marketplace apps, how do I tell if they have restrictions applied that are different to my own?

We have no plans at this time to create an API to share how policies impact other apps installed in the site. If you are building features that interoperate with other apps, please ensure that they are resilient to differing space visibility across apps, or fail gracefully where consistent visibility across both apps is required.

:question: Do you have any additional questions about how to handle app blocking in your app? Please add your comments in this CDAC post


@JuliaDaehne thank you for such a detailed RFC!

Before I start sharing feedback based on the proposal, I do have a process question related to the process of RFC (cc: @ibuchanan).

It boils down to this quote:

Based on this it seems that Atlassian has A) already had discussions with customers shaping her thoughts on this topic and B) already started on the implementation given that you will be starting an early access program in the next quarter.

From the context of an RFC, I would have expected Atlassian to gather feedback from Marketplace Partners in an earlier stage as now it feels more like Atlassian is trying to get finetuning / ironing out the details type of feedback and less of a fundamental discussion on the direction you are taking.


Now to give feedback to the proposal. I also have an additional question (after the feedback)


Given that we need the ability to migrate customers to this new experience, having these web hooks and API’s available will help us provide a beter UX. I would consider this a requirement from an app perspective.

We expect that this is going to lead to a lot of complaints from end-users. To give context: in our Version & Component Sync app we allow users to select a list of “target” projects to which to synchronise their versions/components. If the project they intend to synchronise to will not be in that list, even though they have access to the project, we will get support requests.

To avoid this we will need to be able to give the end-user feedback as to why they cannot select the target project. By omitting the project in the list, without reason, we cannot give them a proper user experience.

In many cases, the end-user will probably not be the one responsible for blocking access. By using a 404 return code, the app cannot determine whether the user made an input mistake (wrong project/space) or whether the user or app does not have access to the project. I would prefer the Atlassian API to be more explicit with return codes and use the 401 forbidden error code instead (if possible with an error message payload that gives a reason).

Yes, we will have to make adjustments in terms of informing end-users about why they will not be able to see certain projects / spaces. See also the point about the HTTP error code, which will allow us to be more explicit about what users can expect. This is specifically important to us because we expect the end-user to be a different person from the one setting the data access policy. As mentioned before, we would like to avert getting customer support requests as to why a project is not available in a list/dropdown/select.

To further drive home the point of why data access policy changes web hooks and REST APIs are a hard requirement for us: if you suddenly stop delivering web hooks because of a data access policy being applied, our app will stop being able to properly process version/component synchronisation. As this is probably applied to someone that did not know our app was listening to these web hooks, we will get support requests to ask why suddenly changes are no longer being propagated.

If we cannot actively notify end-users about this, it might take a few days before customers start noticing and there will be a huge backlog of changes that have not been propagated.

We need to know what happened in order to provide good UX to the end-user about why our app suddenly stopped working.

Yes. Either Atlassian must be absolutely positively clear in her messaging towards the end-users and explain them who to complain to within their organisation or allow us to take control of the narrative and provide a meaningful error message instead. If you bodge this, we will be swamped with customer support requests.

Yes, we have issue view panels and issue context menu’s that will suddenly stop working. The same issue applies as to macros.


What alternatives did Atlassian consider with regard to implementing the “spirit” of giving customers more control over data access?

It seems like you’ve already started descending down the rabbit hole, whilst there might be other paths that would achieve the same goals but with a different impact on UX and marketplace partners.

For instance, have you considered using the already existing User permissions flow to restrict data access, by upgrading the somewhat “magic” app users to actual user accounts that can be given the same type of permissions that can be applied to users / groups?


@remie excellent points.

Yes, this feature is fairly progressed, and work on it has been in flight for quite some time. As a program of work, it actually predates the launch of the RFC process itself. In future, this is exactly the sort of thing we would like to get feedback on earlier in the feature lifecycle via the RFC process.

There was actually some significant discussion internally as to whether the RFC process is really appropriate here. However we decided that since we are actively seeking feedback, it was worthwhile seeking that feedback in a structured manner via an RFC rather than via an ad-hoc CDAC post or other mechanism.


Thanks for clarifying!

I do have a follow-up question: even though this might have predated the RFC process, I would expect Atlassian to understand that this will have a huge impact on the ecosystem. Apart from doing customer research, have you reached out to Marketplace Partners about this prior to this RFC posting?

Actually, I have an additional question:

Can you also clarify how this works with client-side AP.request and user impersonation? Does blocking access for an app mean that the app can also not use AP.request or impersonation to retrieve that list based on user data access?

If AP.request and user impersonation are still allowed, we would have less issues on the UX part. We would still need the data policy change web hooks and REST API’s for the background processing part, but at least we will be able to give the user more context in the UI.


Will you need to make changes to your apps to adapt to the new API behaviours?

We’ll more than likely have to add in messaging in the app with disclaimers about not all data might be available.

Do you foresee your app’s feature set or user experience be negatively impacted by the above changes?

We foresee that our support queues will be flooded with support issues related to projects “missing”. We’d need proper tooling/common language etc that we can steer these customers to. We especially need the project owners to be able to self-service (ie identify) that a policy has been applied to their project easily and not for us to have to help them hunt down the org admin.

How sensitive is your app to API latency?

We’re not sensitive to API latency, however we need the APIs to be consistent. Ie if an issue shows up in the search, we need it to be available in the changelog end point.


Thanks for the detailed RFC @JuliaDaehne!

At least for Confluence spaces, something like this already exists today via space permissions. Space admins can decide to allow or block apps from accessing certain spaces, even controlling whether the app can read, write, or delete content.

I expect that this could get somewhat confusing for customers, as an org admin could allow an app access to a certain space, while the space permissions still block the app. Have you thought about how you will communicate this to both org and space admins in the respective UIs?



Hi @JuliaDaehne ,
Thanks for the RFC.
As an addition to the comment by @SvenSchatter , we have customers blocking app access for some spaces in Confluence. This leads to difficulties for end users, as they often do not understand why a macro or app does “not work” anymore.
If an additional control comes to that, it might get even more confusing for users, and also for us to understand what the problem is.

We also make use of “AP.request”, which sends API requests back the the instance “as a user”. What happens if a user has access rights to a space, but the app has not? We need consistent messaging for this, and just returning 404 to us will not allow us to meaningfully inform customers.


We especially need the project owners to be able to self-service (ie identify) that a policy has been applied to their project easily and not for us to have to help them hunt down the org admin

This is a very important aspect IMHO.

The webhook events would be also substantially important to compile a list of restricted projects on our end, so in the event of a support request, we can easily identify the issue.


Hi @remie - thanks for the equally detailed feedback. It is very much in line with what we heard from a few Marketplace partners already. In particular the concern of increased support cases when end users can’t figure out why their app is not showing anymore. How we handle an app block for an end user, site admin or product admin is critical. We have therefore started to map out a detailed end to end journey from app discovery, app install to app management and the expected experience of an app block at each touchpoint.

Yes, we are planning to test this feature in a closed EAP with 5-10 customers so we can validate our findings. We would also involve the partner of the apps for those EAP customers to close the feedback loop. The EAP feedback should tell us whether or not the feature is acceptable for all stakeholders involved, incl partners.

Your response on proposed APIs and webhooks

“I would consider this a requirement from an app perspective”

confirms our thinking and we have already started to look into this.

As for the user impersonation question I can confirm impersonated users will not receive results for blocked entities.

Interesting point about 404 and 403 errors. Whenever possible a 404 error would be preferable as we don’t even want to disclose the existence of forbidden content. However, this is not always possible as APIs have grown over time and there is no consistent behaviour of returning 403/404 . The current thinking is returning a 404 error for no READ access and 403 for no WRITE access.

1 Like

Is this feature / functionality being designed from the ground up as the technical underpinnings of allowing apps to be licensed for a subset of an instance?

1 Like

That makes sense - is there any other ‘reporting’ or ‘logging’ requirement you would expect to see?

Thanks for clarifying. I think this is going to be a UX bottleneck as it basically means that user impersonation access rights are no longer going to be a binary yes/no answer, but a more ambiguous state in which it can either be the user or the app that lacks permission.


Hi @JuliaDaehne ,
If I understand correctly, Atlassian would send a webhook if e.g. a space becomes inaccessible.
My impression is that an app needs to store these “inaccessible” spaces in order to act on requests for them. This storage seems to me to defeat the reasoning for returning 404’s, and also introduces the storage of “end user data” with additional privacy concerns.

Is there a possibility that Atlassian can send a flag or banner to the user (outside of our app), saying: “App XX has no access to … . Please contact your admin about this.” In that way our apps do not need to receive the names of the forbidden spaces/projects, but the user would get an indication of what is forbidden for the app.


thanks for the fast reply!

One concern would be identifying the blocked project. Lets say I maintain a list of IDs, 10001, 10002 (because only that is available via API) etc., but the customer reports project “EX - Example” does not work. I would then need to guide him to retrieve the ID to double-check.

1 Like

This is already a very tricky thing to do because Atlassian keeps updating Cloud to hide IDs. It is becoming increasingly difficult to match key/name to project ID from the UI.

@remie I can confirm there has been some previous discussion with partners both via individual outreach and in a focus group setting. However as per my previous comment, I do also acknowledge that ideally we would have solicited feedback more broadly, and sooner. We are continuing to improve our feedback processes, and are planning to iterate on and expand the RFC program in FY24.

With that acknowledged, I’d ask that you please do focus on constructive feedback within the scope of the RFC (which I see that you are already providing in spades, thank you!), and avoid further “meta” questions about the timing of the RFC or the nature of previous research. They are reasonable questions, but distract from the main purpose of this RFC, which is to deepen our mutual understanding of the potential app and partner impacts related to this feature in order to identify (and seek to mitigate) risks to customers, partners, and Atlassian.


You’re right, and I should have clarified why I am raising these meta questions. It’s not about the overall process, but specific to this RFC.

The reason I’m asking, is because I’m curious to learn what other options were considered and if Marketplace Partners have been bringing forward alternatives in previous sessions.

More specifically, it is about this question, that unfortunately also has not been answered by Atlassian even though I did get replies on other feedback.

There is a small part of me hoping that we can still turn the ship, although I’m realistic enough to see that we’re beyond that point already.


Ah, that is a great question, but one that I suspect will have a somewhat complex answer.

The armchair architect in me suspects that would only solve part of the problem: e.g. doesn’t cater for data shared in webhooks or context parameters, wouldn’t solve for AP.request() which piggy-back’s the user’s session and ignores that app user (same goes for auth.atlassian.io token exchange), would likely lead to broken experiences in terms of UI modules continuing to be displayed where apps have been built with the previously true assumption that the user has access to data, … I’m sure those are all solvable but I’m not sure we’d end up with a drastically better implementation by the time we’d solved all of those.

That said, the real architects are all asleep so lets wait for them to wake up and hopefully give you a better answer :wink: