API Restrictions

Part of the Administration reference. API Restrictions | Admin Tools | Audit Logs

API whitelist/blacklist

Control which Jira REST API endpoints scripts can access.

Global whitelist

Restrict which Jira REST API endpoints scripts can access (API Whitelist tab of Admin Panel -> Admin).

  • Enabled by default. A new installation and Reset to Defaults start with the admin whitelist (toggle Enable admin whitelist) switched on and filled with the default list.
  • While it is enabled, a script’s requestJira call is sent only if its method and path match an entry of the list. Any other call is rejected before it reaches Jira with the error API call blocked by whitelist: <METHOD> <path>. A rejected call does not count toward the script’s API call limit.
  • Switch it off to allow every endpoint of the built-in (hardcoded) allowed API list; the permanent app-only blacklist, the Application actor restrictions, and the API Blacklist still apply.
  • If Studio cannot read the setting, it uses the last successfully read configuration; without one, it uses the default (enabled).
  • API Catalog (Select from catalog…) for quickly adding common endpoint groups
  • Reset to Defaults restores the default list and switches the whitelist on; it replaces every custom rule
  • The default list includes GET /rest/api/3/attachment/**, so Attachments.copy and issue.copyAttachmentsTo work out of the box. DELETE on attachments is not in the default list - add it yourself if your scripts need it.

Entries and pattern syntax

Each entry is a method (GET, POST, PUT, DELETE or *) and a pattern starting with /rest/, with an optional description (up to 200 characters). Up to 200 entries per list.

Patterns use glob syntax (e.g., /rest/api/3/issue/**):

  • * matches exactly one path segment
  • ** (only at the end of a pattern) matches one or more remaining segments, so /rest/api/3/issue/** does not match /rest/api/3/issue itself
  • {2,3} in a pattern such as /rest/api/{2,3}/issue matches either API version
  • Query parameters are ignored

* /rest/** and patterns targeting app-only endpoints are rejected.

Default list

The default list lets scripts read and change issues but not delete them, and read most of the configuration:

Area Allowed
Issues Create (POST /rest/api/{2,3}/issue); read, create sub-resources and update (GET/POST/PUT /rest/api/{2,3}/issue/**) - no DELETE
Attachments Read and download (GET /rest/api/3/attachment/**) - no DELETE
Search JQL search (GET/POST /rest/api/3/search/jql, /rest/api/2/search), approximate count (POST /rest/api/3/search/approximate-count)
Users Current user (/rest/api/3/myself), user details and search, assignable users - read only
Permissions GET /rest/api/3/mypermissions
Projects Read (/rest/api/3/project, /rest/api/{2,3}/project/**); project properties - read, set and delete
Fields Read, create and update (/rest/api/3/field, /rest/api/3/field/**) - no DELETE
Screens Read, create and update; DELETE /rest/api/3/screens/** (screen sub-resources)
Screen schemes Read only
Field configurations and schemes Read, create and update - no DELETE
Issue types, statuses, priorities Read only
Components, versions Create, read and update - no DELETE
Issue links Create (POST /rest/api/3/issueLink) and delete (DELETE /rest/api/3/issueLink/*); link types - read only
Agile (/rest/agile/1.0/**) Read, create and update - no DELETE
JSM (/rest/servicedeskapi/**) Read everything; create customer requests, update their sub-resources (comments, transitions, participants, approvals), remove a request participant

Everything else - for example any other DELETE, workflows, permission schemes, groups, dashboards and filters - is blocked until you add a matching entry (or switch the whitelist off).

Missing default rules

A whitelist you saved once does not change when the app is updated, so rules added to the default list in later versions (for example, attachment reads and JSM) do not reach it on their own.

When the default list has rules that your saved list does not, the API Whitelist tab in the Admin Panel shows the warning “The default list has rules that your list does not” with the list of missing rules and an Add missing rules button. Add missing rules appends only the missing rules to your saved list; your other rules stay as they are. Without this action, your list does not change.

The blocked by whitelist error of a call that your list blocks but the default list allows also says that the default list allows it - the error ends with:

 - the default admin whitelist allows it; add the missing default rules in Admin Panel (API whitelist)

Global API whitelist configuration

</a>

Global blacklist

Block specific Jira REST API endpoints (API Blacklist tab).

  • Disabled by default (toggle Enable admin blacklist; the default list is empty, nothing blocked)
  • Enable to block matching patterns; same pattern syntax as the whitelist, up to 200 entries
  • Blacklist is checked before whitelist - a matching call is blocked even if the whitelist allows it, with the error API call blocked by global blacklist: <METHOD> <path>
  • Useful for blocking sensitive endpoints while allowing everything else
  • Reset to Defaults clears the list and switches the blacklist off

Global API blacklist configuration

</a>

Custom API restrictions

Create named whitelist/blacklist profiles for per-script restrictions (Script Whitelists and Script Blacklists tabs):

  • Script (custom) whitelists - create named profiles (Create Whitelist) with endpoint patterns and assign them to specific scripts in the script’s Config tab. A script must pass both the global whitelist AND its script whitelist; otherwise the call fails with API call blocked by script whitelist: ....
  • Script (custom) blacklists - create named profiles (Create Blacklist) and assign them in the script’s Config tab. Script blacklists add per-script blocking rules on top of the global blacklist; blacklist rules are always checked before whitelist rules.
  • Up to 50 script whitelist profiles and 50 script blacklist profiles, 200 rules each
  • A profile assigned to scripts cannot be deleted - unassign it first
  • See Limits for all limits

Custom API restriction profiles

</a>


Next steps


JiBrok Studio for Jira Cloud JiBrok Studio for Jira Cloud
Release notes
Core Features
Triggers
Extensions
Data Storage
Scripting Overview
JavaScript Engine
Python Engine
Groovy Engine
Scripting API
Administration
Guides