Scopes

Every object type in the Teamwork Graph API has its own scope. Your app can only read an object type if two things are true:

1. Your app requests the scope for that object type.
2. The site admin grants that scope when they install or configure your app.

Scopes are how a customer decides which slice of their graph your app can see. An admin who is happy for your app to read Jira work items but not Confluence pages can grant one and withhold the other, and your queries keep working for the part they approved.

How scope names work

Teamwork Graph API scopes follow one pattern:

1
2
read:graph:<object>:<product>

So for example ConfluencePage needs read:graph:page:confluence, and JiraWorkItem needs read:graph:issue:jira. All Teamwork Graph API scopes are read-only — there is no write access to the graph through this API.

The scope reference at the end of this page lists the scope for every object type.

Request scopes in your app

Add the scopes your app needs to the permissions block of your manifest.yml:

1
2
3
4
5
6
permissions:
  scopes:
    - 'read:graph:issue:jira'
    - 'read:graph:project:jira'
    - 'read:graph:user:atlassian'

Admin scope restrictions

When configuring Forge apps that interact with the Teamwork Graph, organization administrators can manage and restrict data access using granular Teamwork Graph scopes in Atlassian Administration. From the app's configuration page (Connected Apps > select your app > Permissions), Administrators can toggle individual scopes on or off to grant or revoke access to specific graph entities and relationship types, or use category-level Allow all / Block all bulk controls to manage permissions at scale. When a scope is toggled off, any queries targeting that entity or relationship are blocked server-side, giving organizations fine-grained control over their graph data access.

Moving off the EAP scopes

Apps built during the Early Access Program requested one of two product-wide scopes, read:graph:jira or read:graph:confluence, each of which covered every object type in that product. Those scopes are being retired in favour of the per-object-type scopes on this page.

To migrate:

1. List the object types your app reads, using Work out which scopes you need. A single product-wide scope usually maps to several per-object-type scopes — a Jira app that reads work items, their projects, and their assignees needs three.
2. Replace the product-wide scope in your manifest.yml with those scopes.
3. Redeploy and reinstall. Admins are asked to grant the new scopes, so existing installations need to consent again before your queries return data.
4. Re-test each query, watching for empty results.

Work out which scopes you need

Start from the data your app reads, not from the query you wrote.

For a Cypher query, list every object type the query touches, including types you traverse through but never return. This query needs three scopes, not one:

1
2
3
4
MATCH (user:AtlassianUser {ari: $userId})-[:atlassian_user_assigned_jira_work_item]->(item:JiraWorkItem)
MATCH (item)<-[:jira_space_has_jira_work_item]-(space:JiraSpace)
RETURN space

It returns only JiraSpace, but it reads AtlassianUser and JiraWorkItem on the way there, so it needs read:graph:user:atlassian, read:graph:issue:jira, and read:graph:project:jira.

For a curated query, look at the types the field can return. A field like atlassianUserAssignedJiraWorkItems returns JiraWorkItem, so it needs read:graph:issue:jira plus read:graph:user:atlassian for the user it starts from. The two broad fields, atlassianUserRecentlyViewed and atlassianUserWorkQuery, return a wide union of types — request scopes for the members you want to handle, and the rest are simply left out of the results.

For a persisted Cypher query, the same rule applies as for any Cypher query. Scopes are checked when the query runs, not when you register it, so registering a query successfully doesn't mean your app can execute it against every site.

What happens when a scope is missing

This is the most important thing to understand about scopes:

This is deliberate — the API fails closed rather than leaking data — but it means an empty result set is ambiguous. It can mean "no matching data" or "your app wasn't granted this scope".

Three consequences follow from it.

A missing scope anywhere in the traversal empties the whole result. Both objects and the relationships between them are checked, so in a query of the form A → B → C, lacking the scope for the middle object type B breaks the path even if you hold scopes for A and C.

Mixed traversals return partial results. If a relationship can return several object types and you only hold some of those scopes, you get the types you were granted and silently miss the others. For example, a traversal that can return ConfluencePage, ConfluenceBlogPost, and ConfluenceDatabase returns only pages if read:graph:page:confluence is the only one of the three you were granted.

Scope changes take up to a minute. After an admin enables or disables a scope, allow about a minute before the change is reflected in query results.

Troubleshooting empty results

Work through these in order when a query returns nothing and you expect data:

1. Check your manifest lists a scope for every object type in the query, including intermediate hops.
2. Check the admin granted those scopes for the installation on the site you're querying. A scope your app requests but the admin declined behaves exactly like one you never requested.
3. Wait a minute if a scope was changed recently.
4. Check the end user's permissions. Scopes are applied on top of normal permission filtering, so the user your query runs as still only sees what they can see in the product. See Call the Teamwork Graph API.
5. Narrow the query. Return each object type in the traversal on its own to find which hop comes back empty.

Scope reference

One scope per object type, grouped by where the data comes from.

Jira

Confluence

Atlassian teams, users, goals, and projects

Loom

Compass, Opsgenie, Focus, and Talent

Connected tools

These object types hold data that reached the graph through a connector, such as GitHub, Google Drive, or Slack. The scope covers the object type across every connected tool, so read:graph:pull-request:external covers pull requests from any source.

Getting help

If you need a scope that isn't listed, or a query returns nothing and you've ruled out the causes above, ask in the Atlassian developer community or raise a ticket in the Atlassian Ecosystem Help Center.