The Missing Jira Spoke Implementation Guide (Australia)

chrisbuics · 2 hours ago

The Missing Jira Spoke Implementation Guide (Australia)

Why this exists

I built the Jira spoke by following the OAuth documentation in the Australia release. It worked. Every action the spoke takes is now attributed to my personal Atlassian account, because the documented method requires a licensed human to click Get OAuth Token and approve access. That can't be fixed by changing configuration — it's inherent to the method — and nothing in the documentation told me I was making that choice.

Getting from there to a working service identity took a support case, documentation for a past version, and a conversation with my own team. The short version is below. The full account, and what I think ServiceNow should do about it, is at the end.

This is not a ServiceNow document and comes with no support. I don't work for ServiceNow or Atlassian, I can't help with your instance, and you should verify everything here against your own environment before relying on it. I used an AI assistant to help draft and structure it; the findings and any errors are mine.

If anything here is wrong or has changed, reply and I'll correct the post. Otherwise — I hope it helps.

Start here

If you are seeing this	Go to
Jira issues created by my flows show me as the Reporter	TL;DR
unsupported_grant_type or invalid_client on token request	Tips and Traps
invalid_scope on token request	Scopes
A login/approval window appears when I click Get OAuth Token	Tips and Traps
Token acquires fine, then every action returns 403	Permissions
I switched the grant type to Client Credentials and it broke	Tips and Traps
Client Credentials isn't in my release's documentation	TL;DR
Service accounts don't appear under Directory in Atlassian	Option B

TL;DR

Atlassian gives you two ways to get a Client ID and Secret. That choice decides what identity your integration runs as — not anything you configure in ServiceNow. The two aren't interchangeable and you can't convert one into the other.

Option A Option B

Identity type	Jira Service Account	User Service Account
What it is	A non-user service account in Atlassian Admin	A normal licensed Atlassian user account, used only by the integration
Where you create the credential	Atlassian Admin → Directory → Service accounts	developer.atlassian.com → My apps
ServiceNow grant type	Client Credentials	Authorization Code
Who authenticates after clicking Get OAuth Token	Nobody	The User Service Account
Spoke actions appear as	The Jira Service Account	The User Service Account
Consumes a Jira licence	Check your plan	Yes, one seat
Refresh token	No — 60 min tokens, auto-renewed	Yes, and it can expire
Requires centralized user management	Yes	No
Documented in Australia	No	Yes

Which one:

Is your Atlassian org on centralized user management? If no → Option B.
Can your Jira team grant the scopes you need on a Jira Service Account credential? If no → Option B.
Otherwise → Option A.

Either way, don't let a real employee click Get OAuth Token. That's what the documented procedure leads you into, and it's the whole problem. Option B is only a small change from the documented path — you use a purpose-built account instead of yourself.

Implementation Insight
In the current documentation, the entire consequence of this decision is one line in step 9: "Click the Get OAuth Token related link. In a new window, system requests access to your Atlassian account."
That's it. That sentence is where your integration's identity gets decided, and it reads like a formality. It was the second place a choice could have been surfaced and wasn't.

Scopes

Your Jira team decides what gets granted. Your job in ServiceNow is to request the same set. Requesting something that wasn't granted fails the token request; requesting less than was granted is fine.

These 13 support the documented spoke actions. Drop any whose capability you don't use.

Classic: manage:jira-configuration · manage:jira-project · manage:jira-webhook · read:jira-work · read:jira-user · write:jira-work

Granular: delete:sprint:jira-software · read:issue-details:jira · read:jql:jira · read:sprint:jira-software · write:sprint:jira-software · read:board-scope:jira-software · read:project:jira

Plus one difference between the two options:

Option A (Client Credentials) Option B (Authorization Code)

offline_access

Leave it out — no refresh token is issued and it may be rejected

Required — the flow depends on a refresh token

If your Jira team can only grant 11 of the 13, remove the other two from your OAuth Entity Scopes and your Entity Profile. Don't leave them configured.

Permissions

Scopes are not permissions, and permissions also need to be set by your Jira team. Correct scopes with no project access will authenticate cleanly and then fail in Flow Designer with a 403.

Whichever identity you're using needs, at minimum:

To do this Jira permission

Read and search issues	Browse Projects
Create issues	Create Issues
Update issues	Edit Issues
Transition issues	Transition Issues
Comment	Add Comments
Sprint / board actions	Manage Sprints
Register webhooks	Administrative rights

Grant these per project, only where the integration actually operates. Don't grant site admin to make the 403s stop — it works, and it becomes the finding in your next access review.

Option A: Client Credentials with a Jira Service Account

Before you start

Your Atlassian org must be on centralized user management. If it isn't, service accounts don't appear under Directory — use Option B.
A Jira Service Account must exist. Ask whether it consumes a licence seat on your plan.
Get your Cloud ID from the Atlassian Admin URL: https://admin.atlassian.com/s/<Cloud-ID>/apps

1. Create the Atlassian credential

Your Jira team does this. Atlassian Admin → Directory → Service accounts → select the account → Create credentials → OAuth 2.0 → select scopes → Create.

The Client ID and Secret can't be recovered afterwards. Get them into a secrets manager.

2. Application Registry

All → System OAuth → Application Registry → New → Connect to a third party OAuth Provider

Field Value

Name	e.g. Jira Spoke Cloud
Client ID	From the Jira Service Account credential
Client Secret	From the Jira Service Account credential
Default Grant type	Client Credentials
Token URL	https://auth.atlassian.com/oauth/token
Token Revocation URL	https://auth.atlassian.com/oauth/token
Active	Selected

Leave Authorization URL, Redirect URL, and Refresh Token URL empty. Add your scope records (see Scopes).

3. Check the OAuth Entity Profile — don't skip this

Open the OAuth Entity Profiles tab and the related profile record. Confirm the grant type there is Client Credentials and the scopes match. See Tips and traps — this is the most common thing people miss.

4. Create credential record for the Jira spoke

Just as documented: setup-jira-spk-opt2.html

All → Connections & Credentials → Credentials → New → OAuth 2.0 Credentials

Field Value

Name	Name to identify the credential record for the Jira spoke. For example, Jira cloud OAuth credential.
OAuth Entity Profile	The Client Credentials entity profile you verified in step 3.

Click Submit.
Click the Get OAuth Token related link.

5. Create a connection record for the Jira spoke

Just as documented: setup-jira-spk-opt2.html

All → Connections & Credentials → Connection & Credential Aliases → open the Jira alias that shipped with the spoke → Connections → New

Field Value

Name	Enter any name to uniquely identify the connection record. For example, enter Jira cloud OAuth Connection.
Credential	The credential record above
Connection URL	https://api.atlassian.com/ex/jira/<Cloud-ID>

In Attributes, add api_version = 2 and server_type = cloud.

Implementation Insight
The Zurich Client Credentials page leaves these attributes out. The Authorization Code page requires them. Spoke actions read them to build request paths. Add them.

6. Verify

Run Create Issue and look at the Reporter on the resulting Jira issue. If it shows the Jira Service Account, you're done. If it shows a person, there's still an old token on the credential record.

Option B: Authorization Code with a User Service Account

Use this when Option A isn't available. Follow the documented Authorization Code procedure — the only real difference is who is signed in when you click Get OAuth Token.

1. Create the User Service Account

A normal Atlassian account, ideally provisioned through your IdP, that exists only for this integration.

Name it for its purpose, not its creator — svc-servicenow-jira@ not jsmith-integration@
Give it a monitored mailbox (a team distribution list works) — Atlassian sends security notices there
Store its password and MFA in a shared secrets vault, not one person's phone
Exclude it from leaver and stale-account automation. Nobody logs in after setup, so it will look dormant
Record the owning team somewhere findable — unowned accounts get disabled at access review time
Don't create a ServiceNow login for it

2. Create the Developer console app

developer.atlassian.com → My apps → Create → OAuth 2.0 integration

Authorization → add Callback URL: https://<instance-name>.service-now.com/oauth_redirect.do
Permissions → select your scopes, and include offline_access
Settings → copy the Client ID and Secret

Add the User Service Account and at least one other admin as collaborators on the app, so it isn't administrable by only one person.

Implementation Insight
Collaborator access and Get OAuth Token are different things. Collaborators can administer the app. Identity comes only from who is signed in when Get OAuth Token runs.
Add the account as a collaborator and then click Get OAuth Token while signed in as yourself, and the spoke still acts as you.

3. Application Registry

All → System OAuth → Application Registry → New → Connect to a third party OAuth Provider

Field Value

Name	e.g. Jira Spoke Cloud
Client ID	From the Jira Developer Console
Client Secret	From the Jira Developer Console
Default Grant type	Authorization Code
Authorization URL	https://auth.atlassian.com/authorize
Token URL	https://auth.atlassian.com/oauth/token
Refresh Token URL	https://auth.atlassian.com/oauth/token
Redirect URL	https://<yourdomain>.service-now.com/oauth_redirect.do

Refresh Token URL is hidden on the form by default — configure the form layout to show it.

Add your scopes including offline_access. Create the credential record. Create the connection record with the Cloud ID URL and the api_version / server_type attributes, same as Option A.

4. Get the token as the right account

Sign out of Atlassian and your identity provider (see Tips and traps), or use a private window
Open the credential record → Get OAuth Token
Sign in as the User Service Account
Check the approval screen shows that account, not you
Accept

5. Verify

In Flow Designer, open Create Issue and click test. Confirm the Reporter is the User Service Account.

Tips and Traps

The Entity Profile doesn't follow the Application Registry. When you change the Default Grant type or the scopes on the Application Registry form, you must make the same change on the related record in the OAuth Entity Profiles tab. It does not update automatically. A credential pointing at a profile that still says Authorization Code will keep behaving as Authorization Code no matter what the registry says. Changing the grant type can also leave a second profile behind — open your credential record and confirm which profile it's actually pointed at.
You can't switch grant type in place. Changing an existing Application Registry from Authorization Code to Client Credentials won't work. The Developer console credentials underneath only support authorization_code. You need a new Atlassian credential.
SSO will sign you in as yourself. If your Atlassian access goes through an identity provider (Okta, Entra ID, etc.), signing out of Atlassian isn't enough — the IdP will silently re-authenticate you. Sign out of your IdP too, or use a private window / separate browser profile, before clicking Get OAuth Token. Otherwise you'll get a token for yourself and the whole exercise achieves nothing.
Refresh tokens expire if the integration goes quiet. Under Authorization Code, an unused integration can lose its refresh token — non-production instances are especially prone to this because they sit idle. When it happens, someone has to repeat the interactive Get OAuth Token as the User Service Account. ServiceNow KB2132135 covers this and ways to keep the token alive: KB2132135
Your Jira team may need to allowlist your instance IPs. Under Client Credentials, calls come from the ServiceNow instance itself. If Jira restricts API access by IP, you will be able to get a token, but flow actions will fail. Get your instance IP ranges from ServiceNow HI and hand them over up front.
Old tokens keep working. After you repoint a connection or fix a grant type, the previous credential record still holds a valid token, and the integration will keep running under the old identity until you delete that token. If attribution hasn't changed, this is almost always why.
Check the release in the documentation URL. Both OAuth procedures use the slug setup-jira-spk-opt2.html but serve different content depending on release. A bookmarked or shared link silently changes meaning between versions.

Quick failure lookup:

Symptom	Cause
unsupported_grant_type / invalid_client	Developer console credentials with Client Credentials grant type
invalid_scope	offline_access under Client Credentials, or requesting an ungranted scope
Login window appears under Option A	Grant type is still Authorization Code — check the Entity Profile
Token acquires fine but attribution hasn't changed	Stale token still on the credential record
403 on everything	Jira project permissions missing
401 after a quiet period	Refresh token expired (Option B) — see KB2132135
Calls fail but token is valid	IP allowlisting (Option A)

Message to ServiceNow

I want to be direct about why I wrote this.

I followed your documentation exactly. Every step was accurate. I ended up with an integration authenticating as my personal Atlassian account — a governance problem I then took to support. The support engineer referenced the older Zurich documentation by mistake, and together we concluded that the Jira spoke only supports the documented Authorization Code method. The case was closed on that basis. It wasn't until talking it through internally that we realised Client Credentials is viable, and that the Developer console and the Admin console produce two structurally different credentials.

Your own support organisation could not navigate this. That is the clearest evidence I can offer that the problem is not me.

The problem isn't accuracy. It's that your integration documentation tells people how to execute steps but never tells them what they're choosing. For an integration where the authentication method determines audit attribution and licence consumption, that framing isn't a nice-to-have. It's the most important thing on the page, and it isn't there. The result is that the well-documented path is the one most customers shouldn't use for production automation, and the correct path is one unexplained prerequisite line in a release nobody's on.

Specifically:

Explain the two Atlassian credential sources up front and what each means for identity and licensing, with a clear recommendation for unattended automation.
Restore the Client Credentials option in Australia, or say plainly that it's unsupported. Right now customers on the current release have no documented way to run this spoke as a service identity.
Document the Atlassian Admin console path properly, to the same standard as the Developer console instructions, and link Atlassian's own procedure.
Say that the account clicking Get OAuth Token doesn't have to be a real person, and how to do that properly. "System requests access to your Atlassian account" is not adequate guidance for the step that decides your integration's identity.
State the offline_access difference between grant types. Getting it wrong fails the token request with no obvious cause.
Make the connection attributes consistent across both procedures.
Add migration guidance for people who've already built it the documented way. Many of us have.
Give pages release-distinct URLs so bookmarked and shared links don't silently change meaning.

One more thing, and I mean it as a compliment. The process guides in Best Practice (formerly Now Create) are truly excellent — they tell you how to think about a process, not just how to click through it. I tried to follow that same format above.

You have nothing equivalent for integrations. There's no Jira spoke implementation guide, no Connection & Credentials guide, no guidance on identity and authentication patterns for spokes generally. Just configuration steps. Integration implementation guides, built to the same standard as your process guides, would be enormously valuable — either on the public docs site or on Best Practice. I'd rather find that content from you than write it myself and publish it with a disclaimer saying it's unsupported.

For a company whose product is service management and whose messaging is continual improvement, being the reason customers have to reverse-engineer your own integration architecture is not a good look. Please fix it.

References

ServiceNow

Jira spoke OAuth — Authorization Code (Australia, current): https://www.servicenow.com/docs/r/integrate-applications/integration-hub/setup-jira-spk-opt2.html
Jira spoke OAuth — Client Credentials (Zurich, not in Australia): https://www.servicenow.com/docs/r/zurich/integrate-applications/integration-hub/setup-jira-spk-opt2....
KB2132135 — OAuth refresh token expiry: https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB2132135

Atlassian

Create OAuth 2.0 credential for service accounts: https://support.atlassian.com/user-management/docs/create-oauth-2-0-credential-for-service-accounts

Last updated: September 2026. If something here is inaccurate or out of date, reply and I'll update the post rather than answering in-thread, so the top stays current.