Jira Automation API: Set Auth & Permissions
This guide walks you through setting up authentication and permissions for the Jira Automation API, which lets you programmatically manage automation rules, triggers, and audit logs. You’ll learn how to create an API token, configure OAuth 2.0, and assign the necessary permissions so your scripts can read and modify automation data without hitting 403 or 404 errors.
What You’ll Need
- A Jira Cloud or Jira Server/Data Center instance with admin access (Jira admin or project admin, depending on scope).
- For Cloud: a Jira account with permission to create API tokens (usually any user, but admin recommended).
- For Server/Data Center: a user account with the ‘Administer Jira’ global permission.
- Basic knowledge of REST APIs and HTTP requests (e.g., using curl or Postman).
Step-by-Step
- Identify your Jira version and API endpoint.
- For Jira Cloud, the base URL is
https://your-domain.atlassian.netand the Automation API is under/rest/automation/1.0. - For Jira Server/Data Center (version 8.22+), the base URL is
https://your-jira-instanceand the endpoint is/rest/automation/1.0as well, but authentication differs.
- For Jira Cloud, the base URL is
- Create an API token (Cloud).
- Go to https://id.atlassian.com/manage-profile/security/api-tokens.
- Click Create API token, give it a name (e.g., “automation-script”), and copy the token immediately.
- Use this token with Basic Auth: username is your email, password is the token.
- Set up OAuth 2.0 (Cloud, recommended for production).
- Create an OAuth app in the Atlassian Developer Console.
- Enable the Automation API scope (e.g.,
read:automation,write:automation). - Use the authorization code flow with PKCE to get an access token.
- Include the token in the
Authorization: Bearer <token>header.
- For Server/Data Center: use Basic Auth or PAT.
- Basic Auth: username and password (or a personal access token if enabled).
- If you have PATs enabled, create one in Profile > Personal Access Tokens and use it as the password.
- Grant the required permissions.
- For Cloud: The user must have Administer Jira (global) or Administer Projects for the projects containing the automation rules. Also, the user needs Automation permission, which is granted by default to admins.
- For Server/Data Center: The user must have Administer Jira global permission. There is no separate automation permission.
- Test with a simple GET request.
- Example (Cloud):
curl -u you@email.com:API_TOKEN "https://your-domain.atlassian.net/rest/automation/1.0/rule" - Example (Server):
curl -u username:password "https://jira.example.com/rest/automation/1.0/rule" - If you get a 200 response with a list of rules, authentication works.
- Example (Cloud):
- Set up permissions for specific operations.
- To create/update/delete rules, ensure the user has write:automation scope (Cloud) or is a Jira admin (Server).
- To view audit logs, you need view:automation or admin rights.
- If you’re only reading, a read-only token with
read:automationscope is enough.
- Use the correct headers.
- Always send
Accept: application/jsonandContent-Type: application/jsonfor POST/PUT.
- Always send
Common Mistakes
- Using the wrong authentication method – For Cloud, Basic Auth with API token works, but OAuth is more secure. Mixing them up causes 401 errors.
- Insufficient scopes – For OAuth, forgetting to include
read:automationorwrite:automationleads to 403 errors even if the token is valid. - Wrong base URL – Using
your-domain.atlassian.net/rest/automationinstead of/rest/automation/1.0returns 404. - Not granting admin permissions – On Server, if the user isn’t a Jira admin, they’ll get 403 on most Automation endpoints.
- Storing tokens in code – Hardcoding tokens in scripts is a security risk; use environment variables or a secrets manager.
Tips
- Use a dedicated service account for automation, not a personal account, to avoid disruption if the employee leaves.
- For Cloud, prefer OAuth 2.0 over Basic Auth for production scripts, as it’s more secure and allows fine-grained scopes.
- Check the official Atlassian documentation for the exact list of Automation endpoints and their required scopes, as they can change.
- If you’re using a Jira Server/Data Center, ensure your version supports the Automation API (8.22+).
- Test with a read-only request first to avoid accidentally modifying rules.
Troubleshooting
- 401 Unauthorized – Check your credentials. For Cloud, make sure you’re using email + API token, not email + password. For OAuth, ensure the token hasn’t expired.
- 403 Forbidden – This usually means the user lacks permissions. Verify that the user has admin rights or the correct OAuth scopes. Also check if the project has automation restrictions.
- 404 Not Found – The endpoint might be wrong. Double-check the URL path and version. Also confirm that Automation is enabled in your Jira instance (Cloud: it’s on by default; Server: may need a plugin).
- 429 Too Many Requests – You’re hitting rate limits. Add exponential backoff to your script.
- Empty response on GET /rule – If you get 200 but an empty list, you may not have permission to view rules in any project, or there are no rules yet.
Frequently Asked Questions
- Can I use a personal access token for Jira Cloud Automation API? – No, Jira Cloud does not support PATs; you must use API tokens or OAuth 2.0.
- Do I need to be a Jira admin to use the Automation API? – For Cloud, you need at least project admin rights for the projects containing the rules. For Server, you need global admin rights.
- What is the difference between the Automation API and the regular Jira REST API? – The Automation API is specifically for managing automation rules, while the regular REST API handles issues, projects, etc. They have different endpoints and permissions.
- Can I create automation rules via the API? – Yes, you can create, update, and delete rules using the Automation API, provided you have write permissions.
- How do I get the automation rule ID? – You can list all rules via
GET /rest/automation/1.0/ruleand find theidfield in the response. - Is the Automation API available for Jira Server? – Yes, starting from Jira Server 8.22, but you need to have the Automation plugin installed and licensed.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.