feat(auth): support Atlassian scoped API tokens via Cloud ID#29
Merged
Conversation
Atlassian's scoped API tokens require requests to go through the
Platform API Gateway (api.atlassian.com/ex/jira/{cloudId}) instead
of the site URL. This adds optional Cloud ID configuration that,
when set, automatically routes all REST and Agile API calls through
the gateway.
- Accept cloudId via --cloud-id flag, JIRA_CLOUD_ID env var, or
`jira config set cloudId`
- Route REST (/rest/api/{2,3}) and Agile (/rest/agile/1.0) clients
through the gateway base when cloudId is present
- Keep existing direct routing when cloudId is empty (backward
compatible with classic tokens, Jira Data Center, and Jira Server)
- Surface scoped-token-specific hints on 401 responses
Closes #28
|
🎉 This PR is included in version 2.5.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📋 Summary
Adds support for Atlassian's scoped API tokens by routing REST and Agile API requests through the Platform API Gateway (
https://api.atlassian.com/ex/jira/{cloudId}) when a Cloud ID is configured. Closes #28.Atlassian recommends scoped tokens over classic (unscoped) ones, but they can only be used through the gateway URL. Without this change, scoped tokens fail authentication regardless of how the CLI is configured.
🎯 Type of Change
🔍 Changes Made
lib/config.js): addedcloudIdto the schema, supportJIRA_CLOUD_IDenv var, surface routing mode injira config --showlib/jira-client.js): whencloudIdis set, build REST (/rest/api/{2,3}) and Agile (/rest/agile/1.0) clients offhttps://api.atlassian.com/ex/jira/{cloudId}; otherwise keep the existing${server}/...paths (backward compatible with classic tokens, Jira Data Center, and Jira Server)bin/commands/config.js): added--cloud-id <cloudId>flag, includedcloudIdin connection-test triggers, updated usage messagesconfluence-cli)_edge/tenant_infofor finding the Cloud ID🧪 Testing
jira config --helpexposes the new flagNew unit tests cover:
cloudIdis empty/missing (DC compatibility)cloudIdfrom stored config, returns''when unset, and prefersJIRA_CLOUD_IDenv var over stored config--cloud-idflag wires through toconfig.set('cloudId', ...)📊 Test Results
npm run lintclean.🚀 Deployment Notes
cloudIdsee no behavior change. Cloud ID is opt-in via--cloud-idflag,JIRA_CLOUD_IDenv var, orjira config set cloudId <id>.📝 Checklist
🔗 Related Issues
💬 Additional Notes
A few design choices worth flagging for review:
cloudIdoverapiPath:confluence-clitakes a more flexible approach by letting users configuredomain=api.atlassian.com+apiPath=/ex/confluence/{cloudId}/rest/api. Forjira-cliI picked an explicitcloudIdfield instead because we have two distinct API surfaces (REST and Agile) constructed in code, so a single higher-level abstraction is cleaner. Happy to switch to theapiPathapproach if that's preferred for consistency across the two projects.No auto-discovery: The original issue suggested auto-deriving Cloud ID. I left that out of this PR to keep the surface small —
_edge/tenant_infois documented in the README so users can fetch it manually with one curl. Auto-discovery (calling_edge/tenant_infowhencloudIdis missing) can come as a follow-up.Live testing pending: Unit tests cover URL construction and config plumbing, but I do not have an Atlassian Cloud site with a scoped token to verify the gateway actually accepts the request end-to-end. Recommend a quick live smoke test before merging.