docketbeta
Create your account

Jira — set up the connection

Create the API tokens, connect your Jira site as an admin, and add your personal token as a team member.

Two things have to happen once before anyone can track time on Jira tickets: an admin connects your Jira site, and every team member adds their personal Jira token. New here? Start with the overview.

Creating the service account token

(Admin only. Do this once for the bot/service account.)

The service account token is used by docket to read your Jira projects, issues, and worklogs. It never writes anything to Jira — it only reads.

  1. Log in to Jira with the service account (your dedicated bot account).
  2. Go to id.atlassian.com → Security → API tokens.
  3. Click Create API token.
  4. Give it a descriptive label, e.g. docket – service account.
  5. Select exactly these two scopes — nothing else is needed:
Scope What it's for
read:jira-user Verify the token and read user info (e.g. display names for workload view)
read:jira-work Read projects, issues, and worklogs from Jira
  1. Click Create and copy the token immediately — you won't be able to see it again.
  2. Paste the token into docket when setting up the connection (Part 1 below).

Which account to use? A dedicated service account ("bot") is strongly recommended over a real person's account. If the person leaves and their account is deactivated, the connection breaks. A service account stays active regardless of team changes.

Creating a personal token (each team member)

(Every person who will book time on Jira tickets. Do this once.)

Personal tokens are used to push your time entries to Jira's worklog as you — so the hours appear under your name in Jira, not the bot's.

  1. Go to id.atlassian.com → Security → API tokens with your own Atlassian account.
  2. Click Create API token.
  3. Give it a label, e.g. docket.
  4. Select exactly these two scopes:
Scope What it's for
read:jira-user Verify the token (docket checks it can reach each connected site)
write:jira-work Create, update, and delete your worklogs in Jira
  1. Click Create and copy the token immediately.
  2. Paste it into docket under your profile settings (Part 2 below).

One token works for every Jira site your Atlassian account can access — you don't need a separate token per site.

Part 1 — Admin: connect your Jira site

(Admin only. Do this once per Jira site.)

  1. Go to Admin → Integrations.
  2. Click Add connection and fill in:
    • Name — a label you'll recognise, e.g. "Company Jira".
    • Site URL — https://yourcompany.atlassian.net (docket resolves the Jira cloud_id automatically from this — nothing else to enter).
    • Service account email and API token — the bot account's credentials.
    • Time tracking backend — leave on Jira core worklogs unless your team logs time with Tempo Timesheets (then choose Tempo and enter the Tempo API token).
  3. Click Add connection — docket immediately checks the credential against Jira and shows a green active badge (reachable) or a red auth failed badge (email/token wrong or lacking access — fix it via the ✎ (Edit) button). Use the ↻ (Test) button any time afterwards to re-check, e.g. after rotating the token.

Part 2 — Each team member: connect your Jira token

(Every person who will book time on Jira tickets. Do this once.)

  1. Go to your profile settings (your name → Settings).
  2. Find the Jira token section.
  3. Enter your Atlassian email and API token, leave the scope on Default (all connections), and click Save token.
  4. docket checks your token against each connected site and shows a ✓ / ✗ list:
    • ✓ — your time on that site's projects will sync to Jira.
    • ✗ — your token can't reach that site (usually you don't have access, or you use a different Atlassian account there). Ask your admin, or add a token scoped to that specific connection.

If you skip this step, you can still book time on Jira tickets in docket — it just won't be pushed to Jira. Those entries are flagged "Not in Jira — connect your token." Once you add your token, hit Retry on them and they'll sync.

Questions about accounts and tokens

Where do I find my Jira account ID? In most cases you don't need to — docket reads it automatically when you save your personal token. For an admin manually mapping a docket user to a Jira user (Admin → Integrations → connection → User mapping), start typing a name or email in the Jira user field — docket searches Jira live and fills in the accountId when you pick a match. This requires the connection's service account to have Jira's global "Browse users and groups" permission (Jira admin → Global permissions → grant it to a group the service account belongs to — it doesn't require full Jira admin rights). If the search still comes back empty after that, enter the accountId directly:

  • Via your Jira profile: click your avatar (top right in Jira) → Profile. Your account ID is in the page URL: https://yourcompany.atlassian.net/jira/people/5b10ac8d82e05b22cc7d4ef5
  • Via the REST API: while logged into Jira, open https://yourcompany.atlassian.net/rest/api/3/myself in your browser — the JSON response contains "accountId": "...".

Do I need a Jira licence for everyone? Yes — each person who logs time to Jira needs their own Atlassian account and API token, because their hours are written to Jira as them.

What if we use Tempo for time tracking? Tell your admin — the connection has a Tempo setting. With Tempo, worklogs are written via the Tempo API using the connection token (not personal user tokens), so team members don't each need write:jira-work — they only need read:jira-user on their personal token.

Is my API token safe? Tokens are stored encrypted and are never shown again after you save them. Only you can manage your own token; even admins can't see it.

Next: link a project and start tracking time.