The Jira Cloud REST API reference is Atlassian’s, and nobody’s going to out-document developer.atlassian.com on where an endpoint lives. This page is the other half — the part the reference doesn’t front-load: which auth method to actually pick, what really throttles you (a points budget, not requests-per-second), and the couple of platform changes that quietly broke working scripts in 2025. We ship two Jira integrations at Crosstown Tech — the Microsoft Planner to Jira connector and OneNote Reports for Jira — so this is written from hitting these walls in production, not from paraphrasing the docs.

One number to anchor on: the Jira Cloud REST API’s default budget is a 65,000-point hourly quota, pooled across the traffic hitting a tenant (Atlassian rate limiting docs, verified 2026-08-08). That’s the real ceiling — and almost nobody plans for it until they hit it.

Which auth method should you actually use?

There are three real doors into the Jira API, and picking the wrong one costs you a rebuild.

  • API tokens (HTTP Basic). You mint a token, and send your Atlassian account email plus the token as Basic auth (Atlassian docs). This is the right call for an internal script that acts as one specific user — a nightly export, a cron job, a personal automation. Fast to stand up, no consent flow. The catch: it’s tied to that human’s account and permissions, so it’s the wrong tool the moment you have more than one customer.
  • OAuth 2.0 (3LO). Three-legged OAuth is for an app acting on behalf of many users, each of whom grants scoped consent. This is what a multi-tenant integration needs. It’s also where the gotchas live — see below.
  • Connect / Forge. If you’re distributing on the Atlassian Marketplace, the framework handles auth for you (JWT for Connect, the platform for Forge). Don’t hand-roll OAuth for a Marketplace app.

The rule of thumb we use: one user and one site → API token. Many users, your own hosting → OAuth 2.0 (3LO). Marketplace distribution → Connect or Forge.

The OAuth gotchas that cost a day each

Two facts about 3LO that the happy-path tutorials skip, both verified against the live OAuth 2.0 (3LO) docs on 2026-08-08:

  1. Access tokens die in exactly 60 minutes (expires_in: 3600), and that’s not adjustable. If you’re building anything long-running, refresh logic isn’t optional — it’s the core of the integration. Store the expiry, refresh ahead of it.
  2. Refresh tokens rotate, and rotation invalidates the old one. Each refresh returns a new refresh token and resets a 90-day inactivity clock; if your code doesn’t persist the returned token, your next refresh fails and the user has to re-consent. The number-one “OAuth randomly breaks after a while” bug is a service that refreshes but keeps writing the same original refresh token to disk.

And there’s a step that trips up every first integration: after you get a token you don’t have a site yet. You call GET /oauth/token/accessible-resources to get the cloudid, and that goes into every API URL (/ex/jira/{cloudid}/rest/api/3/...). Skip it and every call 404s.

What actually rate-limits you — it’s not requests per second

Most people budget the Jira API as “requests per second” and get blindsided. The real model is a points-based hourly quota (Atlassian rate limiting docs, verified 2026-08-08):

  • The default pool is 65,000 points per hour, and it’s shared across the apps hitting a tenant (paid tenants can get larger per-tenant pools after review — e.g. Standard is 100,000 + 10 × users).
  • Cost per call: reading core objects is 1 point, identity/access reads are 2, and writes (POST/PUT/PATCH/DELETE) are 1.
  • Layered on top are per-second burst limits (100 GET/s, 100 POST/s, 50 PUT/s, 50 DELETE/s) and — the one that ambushes bulk updaters — a per-issue write cap of 20 writes per 2 seconds and 100 per 30 seconds.

The practical failure mode: you’re doing 30 requests a second — nowhere near the burst ceiling — and you still start getting throttled, because a big backfill drained the hourly points pool. When you’re limited you get 429 Too Many Requests with a Retry-After header. Read that header and honor it. The single most common bad Jira integration retries immediately in a tight loop, digs the hole deeper, and gets nothing done. Exponential backoff keyed off Retry-After isn’t a nicety here — it’s the difference between a job that finishes and one that flatlines.

The pagination change that returned 410 on live scripts

This is the one that bit the whole ecosystem in 2025. Atlassian deprecated the old GET /rest/api/3/search endpoint and moved issue search to /rest/api/3/search/jql (Atlassian issue-search docs; migration thread). Two behavior changes broke working code:

  1. Pagination went cursor-based. The old endpoint gave you startAt, total, and maxResults — classic offset paging. The new one hands you a nextPageToken and you loop until it’s absent. There’s no total to compute a progress bar from anymore. Every script that did startAt += maxResults needs rewriting.
  2. Queries are bounded — you must ask for fields. The new endpoint won’t hydrate fields you don’t request. Teams that migrated the URL but not the fields parameter got back issues that were “empty” — keys with no data — and thought the API was broken.

If you have Jira automation that “just stopped working” or started returning nothing, this is the first thing to check (Adaptavist’s breaking-change note is a clean summary). The lesson we took from it: pin your integration to explicit field lists and cursor pagination from day one, and treat Atlassian’s deprecation notices as work items, not FYIs.

JQL, webhooks, and the rest of the production checklist

A few more that come up every time we wire something into Jira:

  • JQL via the API is user-scoped. A JQL query returns only the issues the authenticating identity can see. The classic bug: your query works in your browser (you’re an admin) and returns fewer rows via the API (the token’s user has narrower permissions). Test JQL as the service account, not as yourself.
  • Webhooks vs polling. For “tell me when something changes,” webhooks beat hammering the search endpoint on a timer — they’re event-driven and don’t burn your points budget on empty polls. But webhooks aren’t guaranteed delivery: a dropped event means silent drift. The robust pattern is webhooks for freshness plus a low-frequency reconciliation sweep to catch anything missed. If you’re deciding between the two for a sync job, we wrote up the webhooks-vs-polling trade-off in the context of a real Rovo/DevOps setup.
  • Expand traps. Fields like changelog and renderedFields only appear when you expand them — and each expand makes the response heavier and the call pricier against your budget. Ask for exactly what you need.

None of this is in the endpoint reference because it isn’t about endpoints — it’s about what the platform does under load, over time, across a real user base.

Would you rather not build this at all?

Half the reason people search “api for jira” is that they’re about to hand-wire something into Jira and want to know what they’re walking into. Sometimes the honest answer is: don’t. If the job is getting Microsoft Planner tasks into Jira, the auth-plus-rate-limit-plus-pagination gauntlet above is exactly what a connector exists to absorb — see how to migrate Microsoft Planner to Jira for the field-mapping side of that, or point the Microsoft Planner to Jira connector at your plan and skip the glue code entirely. If the job is getting Jira issues out to a stakeholder on a schedule, OneNote Reports for Jira already handles the API, the pagination, and the rate-limit backoff so you don’t reimplement them.

Build the integration when the workflow is genuinely yours. When it’s a solved problem, the API you don’t have to babysit is the best API for Jira.