REST API - XSRF and the X-Atlassian-Token header

Data Center This page documents Time in status, Timer, Stopwatch and Calendar fields for Jira Data Center and Server. On Jira Cloud? See Time in Status (Forge) for Jira Cloud.

Base REST URL of the app: {baseUrl}/rest/jibrok/timeinstatus/1.0. This page covers what every caller has to send with a request as of 6.4. The published REST API reference still describes plugin version 5.x and is waiting to be regenerated - where it disagrees with this page, this page is the current one.


The rule

Every request to /rest/jibrok/timeinstatus/* that is not a GET must carry an XSRF token. There are two ways to send it, and either one is enough:

  • A header (recommended) - X-Atlassian-Token: no-check
  • A query parameter - atl_token=<token> appended to the URL
This also applies to server-to-server scripts. Authenticating with a Personal Access Token or with Basic auth does not exempt a request from the check - a script that worked for years without the header stops working after the upgrade to 6.4.

GET requests that only read data are unaffected: nothing has to be added to them.

What happens without the token

The call is rejected by the XSRF check before the app does anything, and you get an XSRF error instead of the action you asked for. Nothing is written and nothing is started - a timer that “silently stopped starting” after an upgrade is the usual symptom in a script that posts without the header.


Example - start a timer

curl -X POST \
  -H "Authorization: Bearer $JIRA_PAT" \
  -H "X-Atlassian-Token: no-check" \
  -H "Content-Type: application/json" \
  -d '{"issueKey": "TEST-1", "customFieldId": 10000}' \
  "https://jira.example.com/rest/jibrok/timeinstatus/1.0/timerManager/start"

The same call with Basic auth and with the token in the query string instead of the header:

curl -X POST -u "$JIRA_USER:$JIRA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"issueKey": "TEST-1", "customFieldId": 10000}' \
  "https://jira.example.com/rest/jibrok/timeinstatus/1.0/timerManager/start?atl_token=$ATL_TOKEN"

Endpoints that changed method

Five endpoints whose path starts with settingsForAll write settings while still answering a GET. As of 6.4:

  • they accept POST only - a GET on them stops working;
  • they need the XSRF token, like every other non-GET call;
  • their parameters are unchanged.

A call is migrated like this:

# before 6.4
curl -u "$JIRA_USER:$JIRA_PASSWORD" \
  "https://jira.example.com/rest/jibrok/timeinstatus/1.0/settingsForAll<Name>?<params>"

# 6.4
curl -X POST -u "$JIRA_USER:$JIRA_PASSWORD" \
  -H "X-Atlassian-Token: no-check" \
  "https://jira.example.com/rest/jibrok/timeinstatus/1.0/settingsForAll<Name>?<params>"

The published REST reference predates these endpoints and does not list any of them, so go by the rule instead: if the path starts with settingsForAll and the call changes a setting, send it as a POST with the token. The names to look for are the ones your own scripts already call.

Read-only endpoints under the same prefix stay GET and need nothing added.


Manual control (JSON body)

start, pause, stop and restart for timers and stopwatches take a JSON body instead of form parameters. All eight commands are sent as a POST:

Counter Endpoints
Timer /timerManager/start, /timerManager/pause, /timerManager/stop, /timerManager/restart
Stopwatch /stopwatchManager/start, /stopwatchManager/pause, /stopwatchManager/stop, /stopwatchManager/restart

All eight commands take the same body:

{
  "issueKey": "TEST-1",
  "customFieldId": 10000
}

Fields of the body:

  • issueKey - issue key, for example TEST-1. Use this or issueId.
  • issueId - numeric issue id, an alternative to issueKey.
  • customFieldId - numeric id of the timer or stopwatch custom field the command applies to.

Send Content-Type: application/json together with the XSRF token. Form-encoded parameters are no longer read for these commands.

The caller also has to be allowed to drive the counter: since 6.4 that means the Browse Projects permission on the issue’s project, plus the groups and roles set in the field configuration. See Manual control for Timers and Stopwatches.


Reports

POST /reportQueue/recover returns reports that were left in the queue - by a node restart in the middle of a generation, for example - to a state where they can be generated again. It is a POST, so it needs the token:

curl -X POST -u "$JIRA_USER:$JIRA_PASSWORD" \
  -H "X-Atlassian-Token: no-check" \
  "https://jira.example.com/rest/jibrok/timeinstatus/1.0/reportQueue/recover"

A table report whose JQL selects more issues than the report issue limit (as of 6.6; 10 000 by default) fails with more than N issues instead of being calculated. See Reports.


Error responses

The body of a 500 response is generic as of 6.4: it no longer describes what failed inside the app. Integrations that parsed the message out of an error body have to rely on the status code instead; the details stay in the Jira log on the server, so send the log excerpt when you open a support case.


Administration pages

The app’s administration screens are behind Jira’s WebSudo: if your administrator session has expired, Jira asks for your password again when you open them. As of 6.4 the same applies to the app’s administrative REST endpoints when they are called with a browser session - a script that scraped the .jspa pages and one that calls those endpoints from the browser both hit the WebSudo prompt.

Authenticate the integration instead: a Personal Access Token or Basic auth is not a browser session and is not asked for WebSudo. Send the XSRF token with it, as above.


Checklist for an existing integration

  1. Find every call your scripts make to /rest/jibrok/timeinstatus/.
  2. Add X-Atlassian-Token: no-check to each one that is not a GET.
  3. Change settingsForAll* writes from GET to POST.
  4. Change manual timer and stopwatch control to a JSON body with Content-Type: application/json.
  5. Check that the account behind the integration has Browse Projects where it drives counters.
  6. Stop parsing 500 bodies.

The rest of what 6.4 changes is in the 6.4 release notes.


JiBrok time in status Time in status | SLA | Timer | Stopwatch
Migration
Release notes
Tutorials
Settings
Troubleshooting
Work calendars
Time in status
Timers and Stopwatches
Stopwatch
Timer
Additional functions
Issue panels
Reports
Field Helpers
Other fields
API
Reference information