# Scopes

> **Note:** The Teamwork Graph API is available through Forge's
> [Preview](/platform/forge/whats-coming/#preview) release phase.
> 
> Preview features are available to all users and receive the same level of support as generally
> available features. Schemas, fields, and behavior may still change before general availability (GA),
> and breaking changes are subject to a minimum **1-month deprecation notice**, announced in the
> [Teamwork Graph changelog](/platform/teamwork-graph/changelog/).
> 
> To review the current limitations, see
> [Limitations and considerations](/platform/teamwork-graph/limitations-and-considerations/).
> 
> To share feedback or report an issue, visit the
> [Atlassian developer community](https://community.developer.atlassian.com/).

Every [object type](/platform/teamwork-graph/api-reference/object-types/overview/) 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.

> **Note:** The [scope reference](#scope-reference) on this page is the definitive list. If you built your app
> during the Early Access Program against the broader `read:graph:jira` or `read:graph:confluence`
> scopes, see [Moving off the EAP scopes](#moving-off-the-eap-scopes).

## How scope names work

Teamwork Graph API scopes follow one pattern:

```
read:graph:<object>:<product>
```

So for example [ConfluencePage](/platform/teamwork-graph/api-reference/object-types/ConfluencePage/) needs
`read:graph:page:confluence`, and
[JiraWorkItem](/platform/teamwork-graph/api-reference/object-types/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](#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`:

```yaml
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](#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.

> **Note:** Declare a scope only for the object types your queries actually touch. One product-wide EAP scope can
> expand into a long list of per-object-type scopes, and Forge currently has a scope cap of 50. See:
> [Forge scopes](/platform/forge/manifest-reference/scopes-product-jira/).

## Work out which scopes you need

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

**For a [Cypher query](/platform/teamwork-graph/graphql-and-cypher/), list every object type the
query touches**, including types you traverse through but never return. This query needs three
scopes, not one:

```cypher
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](/platform/teamwork-graph/curated-queries/)**, 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](/platform/teamwork-graph/persisted-cypher-queries/)**, 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:

> **Warning:** A missing scope doesn't produce an error. The object type is treated as unreadable, so the rows that
> would have contained it are **not returned**. A query that reads an object type you weren't granted
> comes back successful and empty.

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](/platform/teamwork-graph/call-the-teamwork-graph-api/#data-exists-but-not-returned-in-results).
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

| Object type | Scope |
| --- | --- |
| [JiraWorkItem](/platform/teamwork-graph/api-reference/object-types/JiraWorkItem/) | `read:graph:issue:jira` |
| [JiraWorkItemComment](/platform/teamwork-graph/api-reference/object-types/JiraWorkItemComment/) | `read:graph:issue-comment:jira` |
| [JiraWorkItemStatus](/platform/teamwork-graph/api-reference/object-types/JiraWorkItemStatus/) | `read:graph:issue-status:jira` |
| [JiraWorkItemPriority](/platform/teamwork-graph/api-reference/object-types/JiraWorkItemPriority/) | `read:graph:priority:jira` |
| [JiraWorkItemRemoteLink](/platform/teamwork-graph/api-reference/object-types/JiraWorkItemRemoteLink/) | `read:graph:issue-remote-link:jira` |
| [JiraWorklog](/platform/teamwork-graph/api-reference/object-types/JiraWorklog/) | `read:graph:issue-worklog:jira` |
| [JiraSpace](/platform/teamwork-graph/api-reference/object-types/JiraSpace/) | `read:graph:project:jira` |
| [JiraBoard](/platform/teamwork-graph/api-reference/object-types/JiraBoard/) | `read:graph:board:jira` |
| [JiraSprint](/platform/teamwork-graph/api-reference/object-types/JiraSprint/) | `read:graph:sprint:jira` |
| [JiraVersion](/platform/teamwork-graph/api-reference/object-types/JiraVersion/) | `read:graph:version:jira` |

### Confluence

| Object type | Scope |
| --- | --- |
| [ConfluencePage](/platform/teamwork-graph/api-reference/object-types/ConfluencePage/) | `read:graph:page:confluence` |
| [ConfluenceBlogPost](/platform/teamwork-graph/api-reference/object-types/ConfluenceBlogPost/) | `read:graph:blogpost:confluence` |
| [ConfluenceComment](/platform/teamwork-graph/api-reference/object-types/ConfluenceComment/) | `read:graph:comment:confluence` |
| [ConfluenceDatabase](/platform/teamwork-graph/api-reference/object-types/ConfluenceDatabase/) | `read:graph:database:confluence` |
| [ConfluenceFolder](/platform/teamwork-graph/api-reference/object-types/ConfluenceFolder/) | `read:graph:folder:confluence` |
| [ConfluenceSpace](/platform/teamwork-graph/api-reference/object-types/ConfluenceSpace/) | `read:graph:space:confluence` |
| [ConfluenceWhiteboard](/platform/teamwork-graph/api-reference/object-types/ConfluenceWhiteboard/) | `read:graph:whiteboard:confluence` |

### Atlassian teams, users, goals, and projects

| Object type | Scope |
| --- | --- |
| [AtlassianUser](/platform/teamwork-graph/api-reference/object-types/AtlassianUser/) | `read:graph:user:atlassian` |
| [AtlassianTeam](/platform/teamwork-graph/api-reference/object-types/AtlassianTeam/) | `read:graph:team:atlassian` |
| [AtlassianTeamType](/platform/teamwork-graph/api-reference/object-types/AtlassianTeamType/) | `read:graph:team-type:atlassian` |
| [AtlassianGoal](/platform/teamwork-graph/api-reference/object-types/AtlassianGoal/) | `read:graph:goal:atlassian` |
| [AtlassianGoalUpdate](/platform/teamwork-graph/api-reference/object-types/AtlassianGoalUpdate/) | `read:graph:goal-update:atlassian` |
| [AtlassianProject](/platform/teamwork-graph/api-reference/object-types/AtlassianProject/) | `read:graph:project:atlassian` |
| [AtlassianProjectUpdate](/platform/teamwork-graph/api-reference/object-types/AtlassianProjectUpdate/) | `read:graph:project-update:atlassian` |
| [AtlassianHomeTag](/platform/teamwork-graph/api-reference/object-types/AtlassianHomeTag/) | `read:graph:tag:atlassian` |
| [AtlassianHomeComment](/platform/teamwork-graph/api-reference/object-types/AtlassianHomeComment/) | `read:graph:comment:atlassian` |
| [AssetsObject](/platform/teamwork-graph/api-reference/object-types/AssetsObject/) | `read:graph:assets-object:atlassian` |

### Loom

| Object type | Scope |
| --- | --- |
| [LoomVideo](/platform/teamwork-graph/api-reference/object-types/LoomVideo/) | `read:graph:video:loom` |
| [LoomComment](/platform/teamwork-graph/api-reference/object-types/LoomComment/) | `read:graph:comment:loom` |
| [LoomMeeting](/platform/teamwork-graph/api-reference/object-types/LoomMeeting/) | `read:graph:meeting:loom` |
| [LoomMeetingRecurrence](/platform/teamwork-graph/api-reference/object-types/LoomMeetingRecurrence/) | `read:graph:meeting-recurrence:loom` |
| [LoomSpace](/platform/teamwork-graph/api-reference/object-types/LoomSpace/) | `read:graph:space:loom` |

### Compass, Opsgenie, Focus, and Talent

| Object type | Scope |
| --- | --- |
| [CompassComponent](/platform/teamwork-graph/api-reference/object-types/CompassComponent/) | `read:graph:component:compass` |
| [CompassComponentLink](/platform/teamwork-graph/api-reference/object-types/CompassComponentLink/) | `read:graph:component-link:compass` |
| [CompassScorecard](/platform/teamwork-graph/api-reference/object-types/CompassScorecard/) | `read:graph:scorecard:compass` |
| [OpsgenieTeam](/platform/teamwork-graph/api-reference/object-types/OpsgenieTeam/) | `read:graph:team:opsgenie` |
| [FocusFocusArea](/platform/teamwork-graph/api-reference/object-types/FocusFocusArea/) | `read:graph:focus-area:focus` |
| [FocusFocusAreaStatusUpdate](/platform/teamwork-graph/api-reference/object-types/FocusFocusAreaStatusUpdate/) | `read:graph:focus-area-status-update:focus` |
| [FocusChangeProposal](/platform/teamwork-graph/api-reference/object-types/FocusChangeProposal/) | `read:graph:change-proposal:focus` |
| [TalentPosition](/platform/teamwork-graph/api-reference/object-types/TalentPosition/) | `read:graph:position:talent` |
| [TalentWorker](/platform/teamwork-graph/api-reference/object-types/TalentWorker/) | `read:graph:worker:talent` |

### Connected tools

These object types hold data that reached the graph through a
[connector](/platform/teamwork-graph/connector-reference/overview/), 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.

| Object type | Scope |
| --- | --- |
| [ExternalWorkItem](/platform/teamwork-graph/api-reference/object-types/ExternalWorkItem/) | `read:graph:work-item:external` |
| [ExternalDocument](/platform/teamwork-graph/api-reference/object-types/ExternalDocument/) | `read:graph:document:external` |
| [ExternalSpace](/platform/teamwork-graph/api-reference/object-types/ExternalSpace/) | `read:graph:space:external` |
| [ExternalProject](/platform/teamwork-graph/api-reference/object-types/ExternalProject/) | `read:graph:project:external` |
| [ExternalComment](/platform/teamwork-graph/api-reference/object-types/ExternalComment/) | `read:graph:comment:external` |
| [ExternalMessage](/platform/teamwork-graph/api-reference/object-types/ExternalMessage/) | `read:graph:message:external` |
| [ExternalConversation](/platform/teamwork-graph/api-reference/object-types/ExternalConversation/) | `read:graph:conversation:external` |
| [ExternalRepository](/platform/teamwork-graph/api-reference/object-types/ExternalRepository/) | `read:graph:repository:external` |
| [ExternalBranch](/platform/teamwork-graph/api-reference/object-types/ExternalBranch/) | `read:graph:branch:external` |
| [ExternalCommit](/platform/teamwork-graph/api-reference/object-types/ExternalCommit/) | `read:graph:commit:external` |
| [ExternalPullRequest](/platform/teamwork-graph/api-reference/object-types/ExternalPullRequest/) | `read:graph:pull-request:external` |
| [ExternalBuild](/platform/teamwork-graph/api-reference/object-types/ExternalBuild/) | `read:graph:build:external` |
| [ExternalDeployment](/platform/teamwork-graph/api-reference/object-types/ExternalDeployment/) | `read:graph:deployment:external` |
| [ExternalFeatureFlag](/platform/teamwork-graph/api-reference/object-types/ExternalFeatureFlag/) | `read:graph:feature-flag:external` |
| [ExternalService](/platform/teamwork-graph/api-reference/object-types/ExternalService/) | `read:graph:service:external` |
| [ExternalVulnerability](/platform/teamwork-graph/api-reference/object-types/ExternalVulnerability/) | `read:graph:vulnerability:external` |
| [ExternalDesign](/platform/teamwork-graph/api-reference/object-types/ExternalDesign/) | `read:graph:design:external` |
| [ExternalVideo](/platform/teamwork-graph/api-reference/object-types/ExternalVideo/) | `read:graph:video:external` |
| [ExternalCalendarEvent](/platform/teamwork-graph/api-reference/object-types/ExternalCalendarEvent/) | `read:graph:calendar-event:external` |
| [ExternalDashboard](/platform/teamwork-graph/api-reference/object-types/ExternalDashboard/) | `read:graph:dashboard:external` |
| [ExternalDataTable](/platform/teamwork-graph/api-reference/object-types/ExternalDataTable/) | `read:graph:data-table:external` |
| [ExternalRemoteLink](/platform/teamwork-graph/api-reference/object-types/ExternalRemoteLink/) | `read:graph:remote-link:external` |
| [ExternalDeal](/platform/teamwork-graph/api-reference/object-types/ExternalDeal/) | `read:graph:deal:external` |
| [ExternalCustomerOrg](/platform/teamwork-graph/api-reference/object-types/ExternalCustomerOrg/) | `read:graph:customer-org:external` |
| [ExternalCustomerOrgCategory](/platform/teamwork-graph/api-reference/object-types/ExternalCustomerOrgCategory/) | `read:graph:customer-org-category:external` |
| [ExternalCustomerContact](/platform/teamwork-graph/api-reference/object-types/ExternalCustomerContact/) | `read:graph:customer-contact:external` |
| [ExternalOrganisation](/platform/teamwork-graph/api-reference/object-types/ExternalOrganisation/) | `read:graph:organisation:external` |
| [ExternalPosition](/platform/teamwork-graph/api-reference/object-types/ExternalPosition/) | `read:graph:position:external` |
| [ExternalWorker](/platform/teamwork-graph/api-reference/object-types/ExternalWorker/) | `read:graph:worker:external` |

## 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](https://community.developer.atlassian.com/) or
raise a ticket in the
[Atlassian Ecosystem Help Center](https://ecosystem.atlassian.net/servicedesk/customer/portal/3763/group/-1).