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
requestJiracall 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 errorAPI 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/**, soAttachments.copyandissue.copyAttachmentsTowork out of the box.DELETEon 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/issueitself{2,3}in a pattern such as/rest/api/{2,3}/issuematches 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)

</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

</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

</a>
Next steps
- Administration - Core settings overview
- Admin Tools - Script usage, import/export, health check
- Limits - All system limits
