Jira REST API Use Cases — STEAM Security Dashboard
Overview
The STEAM Security Dashboard is a self-hosted vulnerability management tool used by the NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG teams. It integrates with Jira Data Center to create, track, and sync vulnerability remediation tickets linked to CVE records.
All API calls are made from a single Node.js backend process. The integration uses Basic Auth with a service account and enforces Charter's posted rate limits client-side.
Charter Compliance Summary
| Requirement |
Implementation |
| Authentication |
Basic Auth with service account (JIRA_API_USER + JIRA_API_TOKEN) |
| Rate limit — daily |
Client-side enforced: 1 440 requests/day max |
| Rate limit — burst |
Client-side enforced: 60 requests/minute max |
| Inter-request delay — GETs |
1 second minimum between GET requests |
| Inter-request delay — writes |
2 seconds minimum between PUT/POST/DELETE requests |
| Explicit field lists |
Every GET includes ?fields= parameter; /rest/api/2/field is blocked |
| No bulk updates |
Issues are updated one at a time; /rest/api/2/issue/bulk is blocked |
| Bulk reads via JQL |
Multi-ticket sync uses a single POST /rest/api/2/search with JQL, not per-issue GETs |
| JQL scoping |
All recurring JQL queries include updated >= -Xh clause |
maxResults cap |
Search queries capped at 1 000 results per page |
Use Cases
1. Connection Test
|
|
| Endpoint |
GET /rest/api/2/myself |
| Trigger |
Admin clicks "Test Connection" on the Jira settings panel |
| Frequency |
Manual, infrequent (a few times per day at most) |
| Purpose |
Verify service account credentials and connectivity |
| Fields requested |
Default (myself endpoint returns user profile) |
2. Create Issue
|
|
| Endpoint |
POST /rest/api/2/issue |
| Trigger |
User clicks "Create in Jira" from a CVE detail panel |
| Frequency |
Manual, estimated 5–20 per day |
| Purpose |
Create a vulnerability remediation ticket linked to a CVE/vendor pair |
| Fields sent |
project.key, summary, issuetype.name, description |
| Notes |
A local record is also created in the dashboard database linking the Jira key to the CVE |
3. Get Single Issue
|
|
| Endpoint |
GET /rest/api/2/issue/{issueKey}?fields=summary,status,assignee,created,updated,priority,issuetype,project,resolution |
| Trigger |
User clicks "Sync" on a single Jira ticket row |
| Frequency |
Manual, estimated 10–30 per day |
| Purpose |
Refresh a single ticket's status and summary from Jira |
| Notes |
Fields are always specified explicitly per Charter requirement |
4. Update Issue
|
|
| Endpoint |
PUT /rest/api/2/issue/{issueKey} |
| Trigger |
Future feature — local edits synced back to Jira |
| Frequency |
Manual, estimated 5–10 per day when enabled |
| Purpose |
Update issue summary or other fields from the dashboard |
| Notes |
Issues are updated one at a time; bulk PUT is not used |
|
|
| Endpoint |
POST /rest/api/2/issue/{issueKey}/comment |
| Trigger |
Dashboard adds audit trail comments to linked tickets |
| Frequency |
Automated on certain actions, estimated 5–15 per day |
| Purpose |
Maintain an audit trail on the Jira ticket for compliance visibility |
6. Get Transitions
|
|
| Endpoint |
GET /rest/api/2/issue/{issueKey}/transitions |
| Trigger |
Dashboard checks available workflow transitions before moving a ticket |
| Frequency |
Manual, paired with transition calls, estimated 5–10 per day |
| Purpose |
Discover valid status transitions for the issue's current workflow state |
7. Transition Issue
|
|
| Endpoint |
POST /rest/api/2/issue/{issueKey}/transitions |
| Trigger |
User moves a ticket to a new status from the dashboard |
| Frequency |
Manual, estimated 5–10 per day |
| Purpose |
Move ticket through workflow states (e.g., Open to In Progress to Closed) |
8. JQL Search (Bulk Sync)
|
|
| Endpoint |
POST /rest/api/2/search |
| Trigger |
Admin clicks "Sync All" on the Jira tickets panel |
| Frequency |
Manual, estimated 1–3 times per day |
| Purpose |
Bulk-refresh all tracked tickets in a single request instead of per-issue GETs |
| JQL pattern |
key in ("KEY-1", "KEY-2", ...) AND updated >= -24h |
| Fields requested |
summary, status, assignee, created, updated, priority, issuetype, project, resolution |
| Batch size |
100 keys per JQL query; multiple batches if needed |
| Notes |
Stops early if rate limit budget is running low (burst remaining <= 5 or daily remaining <= 10) |
9. Issue Lookup
|
|
| Endpoint |
GET /rest/api/2/issue/{issueKey}?fields=... |
| Trigger |
User looks up a Jira issue by key from the dashboard search |
| Frequency |
Manual, estimated 5–15 per day |
| Purpose |
Quick lookup of any Jira issue to view its current state |
Estimated Daily API Usage
| Operation |
Estimated calls/day |
Method |
Delay enforced |
| Connection test |
2–5 |
GET |
1s |
| Create issue |
5–20 |
POST |
2s |
| Get single issue |
10–30 |
GET |
1s |
| Update issue |
5–10 |
PUT |
2s |
| Add comment |
5–15 |
POST |
2s |
| Get transitions |
5–10 |
GET |
1s |
| Transition issue |
5–10 |
POST |
2s |
| JQL search (sync) |
1–5 |
POST |
2s |
| Issue lookup |
5–15 |
GET |
1s |
| Total estimated |
43–120 |
|
|
Well within the 1 440/day limit. Burst usage stays under 60/minute due to enforced inter-request delays.
Blocked Endpoints
The integration explicitly blocks these endpoints to comply with Charter policy:
/rest/api/2/field — field metadata is never queried; fields are specified in code/rest/api/2/issue/bulk — bulk updates are not used; issues are updated individually
Error Handling
- 429 responses: Surfaced to the user as "Rate limit exceeded. Try again later." No automatic retry.
- 5xx responses: Surfaced as "Jira API error" with the response body for debugging.
- Network failures: Caught and surfaced with the error message.
- Timeout: 15 second timeout per request; surfaced as a timeout error.
UAT Test Evidence
The UAT test script (backend/scripts/jira-uat-test.js) exercises all use cases listed above and produces a log file at backend/scripts/jira-uat-test.log. This log can be attached to or referenced in the ATLSUP approval ticket.
To run:
