docket.rocks
DE Create your workspace

Jira — set up the connection

Connect your Jira site as an admin, then every team member connects their own Jira account with one click.

Two things have to happen once before anyone can track time on Jira tickets: an admin connects your Jira site, and every team member connects their own Jira account — one click and a confirmation on Atlassian's page. 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.

What the service account needs in Jira

It only reads, so it needs no write or admin rights — just enough to see what docket mirrors:

  • Access to Jira — a Jira seat in your Atlassian organization.
  • Read access to every project you link ("Browse projects"). In a team-managed project, add the account under Project settings → Access with the role Viewer. In a company-managed project it needs a project role that has "Browse projects" in the project's permission scheme — often every logged-in user already has it.
  • "Browse users and groups" (global permission) — only for searching Jira people when you map them to docket users (see Questions about accounts and tokens below).

Without read access to a project, Jira doesn't report an error — it just returns no issues. docket checks for that and says so in red under Project → Settings → Jira.

Time is written to Jira by each person through their own connection (Part 2), so they need permission to log work on the issue themselves — the service account doesn't.

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 account

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

docket writes your time to Jira as you, so the hours appear under your name in Jira, not the bot's. For that, connect your own Atlassian account:

  1. Go to your profile settings (your name → Settings) and find the Jira section.
  2. Click Connect with Jira. Atlassian opens and asks whether docket may access Jira for you.
  3. Pick your Jira site and click Accept. You land back in docket.
  4. docket shows Connected as your Jira name and a ✓ / ✗ list of your workspace's Jira sites:
    • ✓ — your time on that site's projects will sync to Jira.
    • ✗ Not shared with docket yet — you didn't pick that site on Atlassian's page. Click Add another Jira site and pick it.
    • ✗ with another message — your Atlassian account can't reach that site (usually you don't have access there). Ask your admin.

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 Jira account." Once you've connected, hit Retry on them and they'll sync.

If the connection stops working (you revoked it in Atlassian, or it went unused for about three months), the Jira section says so and shows a Reconnect Jira button — one click and you're back. Atlassian also asks everyone to confirm the connection again once a year.

Disconnecting: the bin icon next to "Connected as" removes the connection from docket. To withdraw docket's access completely, also remove docket in your Atlassian profile under Connected apps.

Alternative: a personal API token

If Connect with Jira isn't shown, or your company's Atlassian admin has blocked connecting apps (Atlassian then shows a notice on its page), use a personal API token instead:

  1. Go to id.atlassian.com → Security → API tokens with your own Atlassian account.
  2. Click Create API token, give it a label, e.g. docket, and 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 — you won't be able to see it again.
  2. In docket's Jira section, click Use an API token instead, enter your Atlassian email and the token, leave the scope on Default (all connections), and click Save token.

One token works for every Jira site your Atlassian account can access.

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 connect your Jira account. 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 connects it, 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, so team members' own connections are only used to find out who they are in Jira.

Is my connection safe? Your connection (or API token) is stored encrypted and is never shown again. Only you can manage it; even admins can't see it. docket only asks Atlassian for what it needs: reading your Jira work and user info, and writing your worklogs.

Next: link a project and start tracking time.