Outcome
By the end of this lesson, you will be able to connect Jira, explain why classic and scoped API tokens behave differently, and predict which capabilities a scoped token leaves unavailable.
| Tier | Engineer |
| JTBD | ”Get cost findings into the queue our team actually works from.” |
| Personas | Platform Engineer · SRE · Engineering Leader |
| Prerequisites | T2.M2.1.L5 (reading a recommendation card) |
| Time | 9 minutes |
| Bloom verb | Connect (Apply), Explain (Understand), Predict (Analyze) |
1. Concept
Connecting Jira takes five values and an admin. Everything else in this module depends on getting this right once.
CONNECT FROM Settings > Integrations. ADMIN-ONLY.
base URL project key issue type bot email API tokenStored as one more integrations provider row, with the token encrypted in the Config vault. The pattern is the same one every credential in this product follows.
The credential is verified live
THE CONNECT CALL VERIFIES AGAINST JIRA BEFOREPERSISTING ANYTHING.
A successful connect is the proof, surfaced asConnected. A bad token, a missing permission or anunreachable host returns a CATEGORISED error ratherthan a generic failure.Same discipline as cloud accounts and AI providers: no tile turns green on an unverified credential.
The two Atlassian token kinds
This is the part that produces confusing behaviour if you do not know it, and it is entirely Atlassian’s shape rather than ZopNight’s.
CLASSIC TOKEN Authenticates against your site URL directly. Everything works.
SCOPED (GRANULAR) TOKEN REJECTED at the site URL with a 401.
So verification resolves the site's cloudId and re-verifies through the Atlassian API gateway. The resolved REST base is stored and used for every REST call afterwards.
The site URL is still kept, for issue deep-links, which never go through the gateway.Both connect transparently. You do not choose a mode; the verify step works out which kind you handed it.
The one thing a scoped token cannot do
THE INBOUND WEBHOOK REGISTRATION USES A LEGACYSITE-BASED API THAT SCOPED TOKENS CANNOT CALL.
SO WITH A SCOPED TOKEN outbound ticketing WORKS inbound (Jira -> ZopNight) sync NEEDS SETUP
You get the existing "two-way sync needs setup" warning. Registering it needs a classic token and a Jira admin.That asymmetry is worth planning for. If your security team prefers scoped tokens, you can have one-way ticketing immediately and will need a separate conversation for two-way sync.
Connect auto-registers the webhook
ON CONNECT, it registers the inbound webhook in Jiraautomatically, best-effort, pointed at ZopNight'scanonical public ingress.
FALLBACK: manual paste, when the token's user is not aJira admin.
ON DISCONNECT, it de-registers.The de-registration matters. An integration that leaves a live webhook behind pointing at a system you have disconnected is a small mess that outlives the decision to stop using it.
The architecture, and why it is worth knowing
CONFIG owns the connection and the token. Nothing else.
PROVISIONER owns TICKET EXECUTION: the connector, the inbound webhook, the ticket-link ledger, and ticket build. Because creating a ticket is an OUTBOUND ACTION, which is the provisioner's nature, alongside remediation.
RECOMMENDER owns recommendation state and provides the ticket body. It is the SOLE WRITER of recommendation status, and IT NEVER KNOWS ABOUT JIRA.
AGGREGATOR not in the ITSM path at all.Two consequences follow, and they are the useful part:
1. THE DEPENDENCY GRAPH STAYS ACYCLIC. The recommender imports no ITSM code. It publishes a NEUTRAL event and something else decides that means Jira (L3).
2. THE PROVIDER BOUNDARY IS JIRA-FREE. Ticket execution sits behind a neutral connector interface with a provider registry. Adding a second provider such as ServiceNow is implement-the- interface plus register, with no orchestration changes.It is version-agnostic
The provisioner resolves a recommendation by ID SHAPE,routing v1 and v2 identifiers to their respectiveendpoints.
So a ticket can be opened for ANY recommendationregardless of which engine produced it.That is why Snowflake findings (V2-only, T2.M2.12) can be ticketed exactly like AWS findings from the V1 engine, with nothing special configured.
2. Demo
A connection that half-worked, diagnosed:
ATTEMPT 1 Base URL, project key, issue type, bot email, and a token the security team had issued.
Result: Connected, with a warning: "two-way sync needs setup".
THE TEAM'S READING: "partial failure, something is wrong with our credentials."
THE ACTUAL SITUATION: the security team had issued a SCOPED token, which is what their policy requires.
- Verification hit the site URL, got a 401, resolved the cloudId, re-verified through the Atlassian API gateway, and succeeded. That is the designed path, not a workaround. - Outbound ticketing works completely. - The inbound webhook registration uses a legacy site-based API that scoped tokens cannot call, so it could not self-register.
NOTHING WAS BROKEN. One capability was unavailable, and the warning said which.
WHAT THEY DID Week 1: shipped with one-way ticketing. Recommendations open Jira issues; Jira changes do not flow back. That covered the actual use case, which was getting findings into the team's queue.
Week 3: a Jira admin registered the webhook manually using the paste fallback, after a short conversation about what the inbound direction buys (L4).
THE DEEP-LINK DETAIL THAT CONFUSED SOMEONE Tickets opened fine, and their /browse/ links pointed at the site URL rather than the gateway base the REST calls use.
That is deliberate: the resolved REST base is for API calls, and the site URL is kept for human-facing deep-links, which never go through the gateway. A link built on the gateway base would not open for a person.3. Hands-on (6 min)
1. Which token kind will your security team issue? [ ] classic [ ] scoped [ ] unknown If scoped, expect outbound-only until a Jira admin registers the webhook.
2. Connect, and record the exact result: [ ] Connected [ ] Connected + "two-way sync needs setup" [ ] categorised error: ________________________
3. If you got the warning, confirm you understand it: which direction works? ______________________ which needs setup? ______________________
4. Open a test ticket and click its deep-link. Does it open in a browser? Y / N Which base does the link use? [ ] site URL [ ] API gateway base
5. Note who can register the inbound webhook in your org (needs a Jira admin + classic token): ______________________________________________4. Knowledge check
Q1
A team connects Jira with a scoped (granular) API token and sees “Connected” plus a “two-way sync needs setup” warning. This means:
A. Everything worked except inbound webhook registration, which uses a legacy site-based API that scoped tokens cannot call
B. The credential is partially invalid and should be reissued
C. The site URL was wrong and the API gateway was used as a fallback path instead of the configured site URL
D. The project key lacks the required permissions
Show answer
Correct: A. Outbound ticketing is fully functional; registering the webhook needs a classic token and a Jira admin. C describes something that did happen and is not a fallback: a scoped token is rejected at the site URL by design, so verification resolves the cloudId and re-verifies through the Atlassian API gateway. That is the designed path for scoped tokens.
Q2
The recommender owns recommendation state and provides the ticket body, but never knows about Jira. Why does this matter?
A. It keeps the recommender’s binary smaller
B. It prevents the recommender from writing ticket status
C. It keeps the dependency graph acyclic
D. It allows the recommender to run without the provisioner
Show answer
Correct: C. The recommender publishes a neutral event and the provisioner decides that means Jira, so ticket execution sits behind a provider-neutral connector interface and adding ServiceNow is implement-the-interface plus register, with no orchestration changes. The service split follows nature rather than convenience: creating a ticket is an outbound action, which is the provisioner’s job alongside remediation, and the recommender stays the sole writer of recommendation status.
Q3
A Snowflake recommendation comes from the V2 engine while an AWS one comes from V1. Ticketing:
A. Works only for V1 recommendations today
B. Works for both
C. Requires a separate integration per engine
D. Works for V2 only after a migration
Show answer
Correct: B. The provisioner resolves a recommendation by ID shape and routes to the right endpoint, so a ticket can be opened for any recommendation regardless of which engine produced it, with nothing special configured. Version-agnosticism is deliberate and it is why the feature did not need revisiting when Snowflake arrived as a V2-only provider.
5. Apply
Find out which token kind your security team will issue before you plan the rollout. Scoped tokens are increasingly the default and they give you one-way ticketing immediately, with the inbound direction as a separate, small conversation.
Confirm the webhook de-registers on disconnect if you are trialling this. An integration that leaves a live webhook pointing at a disconnected system is a mess that outlives the decision.
Related lessons
- L2: A ticket from a recommendation (next)
- L4: Bi-directional sync
- T2.M2.12.L4: The V2 recommendation catalog
- T1.M1.1.L1: Vault credentials
Glossary terms touched
Scoped token · cloudId · Connector interface · Inbound webhook