Skip to content

Documentation · Task

Permissions

Every read and write is checked against the signed-in Jira user, an explicit scope and, for repository data, a current grant. A scope alone is never enough.

Three layers of access

  1. Atlassian validates the request first. App REST calls use OAuth 2.0 (3LO) and the custom scopes below. A site administrator must opt in to App REST APIs for TestWarden in Atlassian Administration → Connected apps.
  2. TestWarden checks the current user. The installation comes only from the Forge runtime, never from the request. A missing identity or a failed permission lookup denies access. There is no app-level or offline-impersonation fallback.
  3. TestWarden checks the repository. Reads need an active grant for that user, installation and repository. A revoked, expired or foreign grant releases no decision data.

Access for CI and developer clients is provisioned during early access and pilot onboarding. You do not create your own integration or use personal access tokens. See Onboarding.

Jira scopes

Marketplace V1 — publicly listed

  • read:jira-work for project and issue discovery, requirement links, coverage and permission lookup.
  • write:jira-work for Jira Bug creation that a user starts from a failed or blocked step.
  • report:personal-data for Atlassian's weekly personal-data reporting. It grants no Jira data access.

More on Security.

App roles

TestWarden maps your Jira permissions to app roles.

RoleCan
ViewerRead.
TesterExecute tests and link defects. Minimum role to read a change and decision over the API.
QA ManagerAuthor tests, views, folders, cycles and links. Required to request an approved rerun and to receive the detailed failure diagnosis.
QA AdminAlso archive, restore and run migrations. Operations that are not classified fail closed to Admin.

Custom scopes and routes

Scopes are least privilege and cannot edit policy, grant approval or accept a caller-selected state.

OperationRouteScopeAlso requiredAvailability
Submit evidence and evaluatePOST /warden/evidencewrite:warden-evidence:customCurrent Jira site administrator and active entitlementMarketplace V1 — publicly listed
Read a change and its latest decisionGET /warden/change?id=<uuid>read:warden-changes:customTester or higher and an active repository read grantMarketplace V1 — publicly listed
Developer reads (status, obligations, plan, evidence, explain)GET /developer/v1/...read:warden-developer:customTester or higher and an active repository read grantDeveloper preview — live acceptance pending
Request an approved rerunPOST /developer/v1/verification/requestrequest:warden-verification:customManager role, entitlement, repository grant and a separately approved runNot yet available (no dispatcher installed)

Add the Forge product scope read:forge-app:jira to the 3LO integration, as Atlassian's App REST setup guide describes. Details for each developer route are in API, CLI and MCP.

Who can write evidence

Evidence write authority is installation-wide. A site administrator holding write:warden-evidence:custom can submit evidence for any repository in that installation. A repository read grant never authorizes a write, import, model call or approval, and per-repository write grants are not implemented.

For that reason, keep the evidence token in the CI system only. Coding agents never hold it. The provider type in a payload is caller-asserted, so token custody is the identity boundary. TestWarden does not store third-party OAuth credentials.

Revocation and licensing

  • Role and grant are checked again before delivery. A change in either releases nothing further.
  • Developer API reads write an audit event.
  • An inactive subscription still permits an otherwise authorized read. Submitting evidence requires an active entitlement.
  • Missing identity returns 401. Authorization or license denial returns a bounded 403 with no decision data.

Troubleshooting

  • 403 on submit. The caller is not a current site administrator, lacks the evidence scope, or the entitlement is inactive.
  • 403 or forbidden on read. The Jira role is below tester, the repository grant is missing or revoked, or App REST APIs are not enabled.
  • 401. The token is missing, expired or not tied to a signed-in user.

Ask your Jira administrator about roles. For grants and provisioning, email [email protected].

Related tasks