Skip to content
Leverage AI Developer Support

Jira Connector

Use this page when you need the Atlassian-side setup details for the Jira connector. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

Section titled “Runtime Shape”
  • Implemented modes: live only
  • Implemented auth bindings:
    • Better Auth generic OAuth provider id atlassian
    • Jira Data Center user-managed PAT through the web app user-api-key strategy
    • Jira Data Center company-managed service/bot PAT through the customer CMS deployment-api-key profile
  • Callback URI examples:
    • http://localhost:3001/api/auth/oauth2/callback/atlassian
    • https://auth.example.com/api/auth/oauth2/callback/atlassian
  • Setup console URL:
  • Required connector scopes:
    • offline_access
    • read:me
    • read:jira-work
    • read:jira-user
  • Data Center credential setup:
    • User-managed PATs are entered in the web app.
    • Company-managed service/bot PATs are entered in customer CMS.

User-Facing Strategy Choice

Section titled “User-Facing Strategy Choice”
  • OAuth remains the default Jira strategy for Atlassian Cloud-style personal account access.
  • “Use your own access token” is the normal Jira Data Center path for a web user who should connect as their own Jira user.
  • “Use company-managed access” uses the CMS service/bot PAT. The provider sees the service/bot user, not the signed-in web user.
  • Company-managed access should be treated as a last-resort or operator-directed strategy for shared service-account visibility, not a substitute for personal identity when the user asks about “my” Jira work.

Company-Managed PAT Setup

Section titled “Company-Managed PAT Setup”
  • Create a dedicated Jira service/bot user.
  • Grant that user only the projects and issue data the deployment connector should expose.
  • Create a Data Center personal access token for that service/bot user.
  • Enter the Jira base URL and PAT in customer CMS. The PAT is stored only through the secret slot backend; the CMS record stores safe readiness/config metadata.
  • Do not enter a Jira Cloud site URL or https://api.atlassian.com/ex/jira/<cloudId> in this profile. Cloud API tokens use email-plus-token Basic auth and should use Atlassian OAuth in the web app unless a separate Cloud API-token profile is accepted later.
  • If validation fails, CMS does not save the attempted Jira URL or PAT. Correct the URL/PAT and validate again.
  • If the company-managed PAT must be removed, use the CMS remove action. It clears the saved PAT slots and Jira setup fields, and any existing company-managed Jira connectors in the web app become unavailable until an operator validates a new PAT. It does not delete users’ OAuth Jira connectors or user-managed PAT connectors.

User-Managed PAT Setup

Section titled “User-Managed PAT Setup”
  • The signed-in web user enters their own Jira Data Center base URL and PAT in the web app.
  • API validates the PAT with Jira, encrypts it in API-owned user credential storage, and scopes it to that user’s connector record.
  • The credential is not stored in CMS and is not usable by other app users.
  • Atlassian Cloud API tokens are not accepted by this Data Center PAT path. For Jira Cloud, use the OAuth strategy; successful local PAT testing requires a reachable Jira Data Center or Server instance with a real PAT.

Provider-Specific Gotchas

Section titled “Provider-Specific Gotchas”
  • Jira is live-only in this repo. There is no indexed sync fallback, Meltano tap, or embeddings path for Jira V1.
  • OAuth Jira connectors store one explicit siteId. Do not infer the site from the access token and do not treat the linked Atlassian account as enough by itself.
  • The same linked Atlassian account may be reused for more than one OAuth Jira connector only when each connector points at a different siteId; that site value is Jira OAuth’s connector scopeKey.
  • The web app should show the Jira site name on connected rows when the provider can resolve it, while still persisting and deduping by siteId.
  • If the only available Jira site is already connected for the selected Atlassian account, the add flow should leave the site field unselected instead of auto-selecting a duplicate.
  • Jira Data Center company-managed connectors do not use siteId; they use the deployment identity deployment:jira and the customer CMS base URL.
  • Jira Data Center PAT validation rejects Atlassian Cloud gateway/site URLs before storing or sending the PAT, so a Cloud URL in CMS indicates the wrong auth strategy rather than a copied-token problem.
  • Company-managed Jira connectors fail closed when the CMS profile is not ready. The web app should show that company-managed access needs operator validation instead of offering chat access with stale setup metadata.
  • Project selection is scoped to the selected Jira site for OAuth or the configured Jira Data Center base URL for company-managed access. Changing site/base URL or project scope is an operator/user reconfiguration step, not an implicit runtime discovery step.
  • Jira’s resourceSelectionPolicy is required: the create/settings flow must not save a Jira connector until the chosen site has an explicit all-project or selected-project scope.
  • Work-item live search resolves person/activity prompts through Atlassian user search before issue JQL, so person-scoped questions such as “what did Jordan do yesterday” need read:jira-user in addition to issue read access.
  • The Connectors page can show multiple Jira connectors under the same Atlassian account when they target different sites.
  • Company-managed access answers are limited by the service/bot user’s Jira permissions and the app user’s selected project scope. They are not proof of the web user’s own Jira account permissions.
  • User-managed PAT answers are limited by the Jira user represented by the signed-in user’s encrypted PAT and the connector’s selected project scope.
  • Personal identity prompts such as “my open Jira issues” must not run through company-managed access as if the signed-in web user were the Jira service/bot account.

Canonical Sources

Section titled “Canonical Sources”
  • packages/domain/src/connectors/connectorRegistry.ts
  • packages/domain/src/connectors/jiraScopes.ts
  • apps/auth/src/genericOAuthProviders.ts
  • apps/api/src/connectors/oauthTokenClient.ts
  • apps/api/src/connectors/userCredentials/defaultUserConnectorCredentialService.ts
  • apps/api/src/connectors/userCredentials/userConnectorCredentialService.ts
  • docs/features/connectors/spec.md

Official Docs

Section titled “Official Docs”