Tool
Jira Cloud
As an integration target Jira Cloud is capable and well specified. There is a published OpenAPI document, the create, update, comment and transition endpoints all exist and all work, and basic auth with an account email and an API token is enough to get a script working in an afternoon. The awkwardness is elsewhere. Field content on the v3 API is Atlassian Document Format, not a string, so the first thing most integrations get wrong is the description field. Rate limiting is three independent systems running at once rather than one number. And Atlassian has been steadily narrowing what an unpublished integration is allowed to do: from 2 March 2026 the new points-based and tiered quotas apply to Forge, Connect and OAuth 2.0 apps, while API token traffic stays on the existing burst limits.
What the API exposes
- Issue creation at POST /rest/api/3/issue, requiring the Browse projects and Create issues project permissions, or the write:jira-work OAuth scope.
- Bulk issue creation at POST /rest/api/3/issue/bulk, up to 50 issues in one call.
- Issue update and delete at PUT and DELETE /rest/api/3/issue/{issueIdOrKey}.
- Comments at POST /rest/api/3/issue/{issueIdOrKey}/comment.
- Workflow transitions at POST /rest/api/3/issue/{issueIdOrKey}/transitions, with GET on the same path to discover which transitions are currently available.
- A create metadata endpoint that tells you which fields the target project and issue type will actually accept, which is the only reliable way to build a payload that does not get rejected.
- Two documented authentication schemes, basic auth using an Atlassian account email address plus an API token, and OAuth 2.0 with per-operation scopes.
- Informative rate limit headers, including Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and a RateLimit-Reason that names which of the three limits you hit.
- SCIM 2.0 inbound user and group provisioning at the Atlassian organization level.
What it cannot do
- Take a plain string for rich fields. On the v3 API the description and environment fields, and any multi-line custom field, take Atlassian Document Format. Single line textfield custom fields take a string and do not handle ADF. Getting this backwards is the single most common cause of a 400 on issue create.
- Be authenticated with a password. Password authentication is deprecated; basic auth means an API token.
- Be integrated at scale with individual API tokens without breaching Atlassian's own guidance. Apps that collect API tokens or tell customers to create their own 3LO apps are documented as not complying with Atlassian's security requirements for cloud apps.
- Be sized from one rate limit. Three independent systems apply at once: a points-based hourly quota, a per-second burst limit with its own token bucket per endpoint per tenant, and a per-issue write limit. You can be well inside your hourly quota and still get a 429.
- Buy more burst headroom by adding users. The per-second burst limit is independent of the number of users in the tenant.
Capabilities
Connects to
Evidence
- Jira Cloud platform REST API v3 OpenAPI document
Atlassian's own machine-readable spec. Source of every endpoint path above, the 50 issue bulk limit, the write:jira-work scope, the permissions each operation requires, and the Atlassian Document Format wording on description and multi-line custom fields.
VENDOR DOC · Checked
- Jira Cloud rate limiting
Source of the three simultaneous limit systems, the token bucket model, the default per-second figures, the response headers and RateLimit-Reason values, and the 2 March 2026 enforcement date for the new quotas.
VENDOR DOC · Checked
- Basic auth for REST APIs
Confirms password auth is deprecated, that basic auth means email plus API token, and carries Atlassian's notice that collecting API tokens or asking customers to create their own 3LO apps does not comply with its cloud app security requirements.
VENDOR DOC · Checked
- Understand user provisioning
Source for SCIM 2.0 inbound provisioning at the organization level.
VENDOR DOC · Checked