API Tokens | Sync Bridge for Jira Cloud | mgm Marketplace App Documentation

📘 What you will learn here

On this page you will learn how Jira admins create, review and revoke the API tokens that authenticate calls to the Sync Trigger API.

Each token belongs to one sync rule and one direction. A push token can only push through that rule, and a pull token can only pull. See Sync Trigger API.

Before you start

You need to be a Jira admin. Tokens are managed in the Sync Bridge admin page.
Your Sync Bridge license must be Advanced or a trial. On Standard, new tokens are refused with The web trigger (API) needs an Advanced license. You can still revoke existing tokens. See License Editions.
The sync rule must be saved. For a new rule, the editor shows Save the rule, then add a token for each service that will call it.
Push (or Pull) must be turned on for the rule, and its API trigger must be turned on. The token list only appears in the details of a turned-on API trigger.

Find the token settings

In the Sync Bridge admin page, open Sync rules and open the rule.
On the Configuration tab, under Sync direction, find the Push or Pull panel and its Triggers.
Turn on API (Start a sync from Jira automation or another service. for push, Start a pull from Jira automation or another service. for pull).
Select the arrow (Show details) next to API. You see the Endpoint, the Push API tokens or Pull API tokens list and View example request.

Create a token

Under Push API tokens or Pull API tokens, select Add token. The token is created for that direction.
In Token name, name the service that will use the token, for example Jira automation.
In Expiration, choose Never, 30 days, 60 days, 90 days or 365 days.
Select Create token.
In the Copy your token now dialog, copy the token with the copy icon and store it somewhere secure.
Select Done.

The token is shown only once. Sync Bridge stores only a hash of it, so nobody can show it again. If you lose it, revoke it and create a new one.

Rules for tokens

Setting	What it does	Notes
Token name	Identifies the calling service.	Required, up to 50 characters, unique within the rule across push and pull tokens (not case-sensitive). The name appears in the Sync History tab as API · token name, which anyone who can view the work item can see, so don't include anything sensitive.
Expiration	When the token stops working.	Never, 30, 60, 90 or 365 days after creation. It can't be changed later. Create a new token instead.
Tokens per rule	How many tokens one rule can have.	Up to 10 push tokens and 10 pull tokens. When a direction has 10, Add token is disabled until you revoke one.

Tokens start with sbt_, followed by a random string.

Review tokens

Each token in the Push API tokens and Pull API tokens lists shows:

Its name.
The last four characters, for example •••a1B2, so you can match it to the token a service uses.
Last used: when the token last authenticated a call, or Never. This is updated at most about once a minute.
Its expiry: Never expires, Expires in n days (highlighted when 14 days or fewer are left) or Expired.

A caller using an expired token gets an error that says when the token expired. Replace expiring tokens before they lapse.

Revoke a token

Under Push API tokens or Pull API tokens, select the delete icon (Revoke token) next to the token.
Select Revoke token to confirm.

The token stops working immediately. Any service that still uses it can't trigger syncs. Revoking can't be undone.

Deleting a sync rule also deletes all its tokens.

Good practice

Create one token per calling service, so you can revoke one without breaking the others.
Keep tokens in a secret store, for example your automation tool's secret settings. Don't put them in code, tickets or chat.
Prefer tokens that expire, and check Last used to find tokens nobody uses any more.
If a token may have leaked, revoke it right away and create a new one.