How to Get a Jira API Token (Step-by-Step)

To get a Jira API token, log in to id.atlassian.com/manage-profile/security/api-tokens, select Create API token (or Create API token with scopes), name it, set an expiration of up to 365 days, and copy the value immediately — it's shown only once. Use that token as the password in HTTP Basic Auth, paired with your Atlassian account email, to call the Jira Cloud REST API.

The rest of this page covers scoped vs. unscoped tokens, where the credential goes on a request, a working code sample, and the errors you'll hit if something's misconfigured.

Prerequisites

• An Atlassian account with access to the Jira Cloud site you want to call (https://your-domain.atlassian.net).
• Two-step verification or SSO doesn't block token creation, but if you log in with a password or third-party login, Atlassian emails you a one-time passcode to verify your identity before you can create or manage tokens (Atlassian Support, Manage API tokens).
• If you need an app to act on behalf of other users (not just your own account), you want OAuth 2.0 (3LO) instead — see the note near the bottom of this page.

Step-by-step: creating a Jira API token

1. Log in to id.atlassian.com/manage-profile/security/api-tokens.
2. Select Create API token with scopes (recommended) or Create API token for an unscoped token.
3. Give the token a name that describes what it's for, e.g. "jira-sync-prod".
4. Set an expiration date — anywhere from 1 to 365 days. New tokens default to a 1-year expiry. If you have an old token created before December 15, 2024 that you haven't replaced yet, it has already expired — Atlassian transitioned all pre-Dec-2024 tokens to expire between March 14 and May 12, 2026, and that window has passed (Atlassian Support, Manage API tokens).
5. If you chose scopes, pick Jira as the app and select the scopes the integration needs — for example read:jira-work for read-only access or write:jira-work to also create and update issues (Atlassian Support, Manage API tokens).
6. Select Create, then Copy to clipboard and store the token in a secrets manager or environment variable. Atlassian cannot show it to you again — if you lose it, revoke it and create a new one.

Where the credential goes

Jira Cloud's REST API uses HTTP Basic Authentication, with your Atlassian account email as the username and the API token as the password (Atlassian Developer, Basic auth for REST APIs):

Authorization: Basic base64(email:api_token)

Most HTTP clients build this for you — with curl, pass -u email@example.com:api_token.

Connector-specific gotcha: if you created an API token with scopes, requests must go to api.atlassian.com/ex/jira/{cloudId}/..., not your normal https://your-domain.atlassian.net/... base URL. Unscoped (legacy) tokens still work against your-domain.atlassian.net, but scoped tokens are routed through Atlassian's gateway using your site's cloudId (Atlassian Support, Manage API tokens).

A few other things to know:

• Lifetime: 1–365 days, set at creation. There's no separate "refresh" — when a token expires, you generate a new one and update wherever it's stored.
• Scopes: prefer scoped tokens with the narrowest scope that works (read:jira-work if you're only reading issues). Unscoped tokens inherit the full permission set of the account that created them.
• Revocation: revoke a token any time from the same API tokens page — it stops working immediately and can't be recovered.

If you need OAuth 2.0 (3LO) instead

If your integration needs to act on behalf of multiple Jira users (not just your own account), use OAuth 2.0 (3LO): register an app in the Atlassian developer console, enable OAuth 2.0 (3LO) under Authorization, then direct users through https://auth.atlassian.com/authorize to get an authorization code, and exchange it at https://auth.atlassian.com/oauth/token for an access token and (with the offline_access scope) a rotating refresh token (Atlassian Developer, OAuth 2.0 (3LO) apps). Refresh tokens expire after 90 days of inactivity, and each use issues a new refresh token that replaces the old one.

Minimal working example

This calls GET /rest/api/3/myself, which returns the profile of the authenticated user — a good smoke test for a new token.

curl:

curl -X GET \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "https://$JIRA_DOMAIN.atlassian.net/rest/api/3/myself"

Node.js:

const auth = Buffer.from(
  `${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`
).toString("base64");

const res = await fetch(
  `https://${process.env.JIRA_DOMAIN}.atlassian.net/rest/api/3/myself`,
  {
    headers: {
      Authorization: `Basic ${auth}`,
      Accept: "application/json",
    },
  }
);

const data = await res.json();
console.log(data.displayName);

Store JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_DOMAIN as environment variables — never hard-code the token.

Common errors and fixes

Why am I getting a 401 Unauthorized?

‍Either the email/token pair is wrong, the token has expired, or it was revoked. Regenerate a token from id.atlassian.com/manage-profile/security/api-tokens and confirm you're using the Atlassian account email, not a username, as the Basic Auth username (Atlassian Developer, Basic auth for REST APIs).

Why does my request fail with an X-Seraph-LoginReason: AUTHENTICATION_DENIED header?

‍Jira triggers a CAPTCHA after several consecutive failed logins, and the REST API can't complete a CAPTCHA challenge. This header means the login was rejected before the password was even checked. Log in to the Jira web UI once to clear the CAPTCHA, then retry the API call (Atlassian Developer, Basic auth for REST APIs).

Why does refreshing my OAuth token return 403 invalid_grant?

‍This means the refresh token is unknown or invalid — usually because the user changed their Atlassian password, the refresh token expired after 90 days of inactivity, or your app didn't store the new rotating refresh token from the previous exchange. If it's expired, the user needs to redo the full authorization flow (Atlassian Developer, OAuth 2.0 (3LO) apps).

The faster way

Generating and rotating a Jira API token works fine for one integration. It gets harder once you're connecting Jira alongside other ticketing tools — each with its own token formats, scoped-vs-unscoped routing quirks, and refresh schedules. Knit's unified ticketing API handles Jira's auth (including the scoped-token cloudId routing above), normalizes issue and project data across connectors, and refreshes credentials automatically. See the Jira API overview for what's available, or book a demo to see it against your own Jira site. You can also sign up free and connect a sandbox Jira instance in a few minutes.

FAQ

Where do I find my Jira API token after creating it?

‍Atlassian shows the token value only once, immediately after you click "Create." Copy it then — if you lose it, revoke the old token and create a new one. Existing tokens (without their values) are listed at id.atlassian.com/manage-profile/security/api-tokens, where you can see names, expiration dates, and scopes.

What's the difference between a Jira API token and OAuth 2.0 (3LO)?

‍An API token authenticates as you via Basic Auth — simple, but tied to one Atlassian account. OAuth 2.0 (3LO) lets an app act on behalf of other users after they grant consent through an authorization screen, and issues short-lived access tokens plus rotating refresh tokens. Use a token for personal scripts and internal automation; use OAuth 2.0 (3LO) for an app that multiple Jira users will install.

Do Jira API tokens expire?

‍Yes. New tokens expire 1–365 days after creation, whichever date you set (1-year default). Tokens created before December 15, 2024 were transitioned under Atlassian's policy change and have already expired as of May 2026 — if you're still relying on one of those, generate a replacement now. There's no auto-renewal otherwise — generate a new token before the current one expires and update it wherever it's stored.

Why do I need my site's cloudId for some Jira API calls?

‍Scoped API tokens and OAuth 2.0 (3LO) apps both call the Jira API through api.atlassian.com/ex/jira/{cloudId}/... rather than your-domain.atlassian.net. Get the cloudId by calling GET https://api.atlassian.com/oauth/token/accessible-resources (for OAuth) — for scoped API tokens, the same gateway pattern applies using your site's cloud ID.

Is the Jira API free to use with an API token?

‍Yes — creating a token and calling the Jira Cloud REST API costs nothing beyond your existing Atlassian subscription. Usage is governed by Jira's rate limits: a 65,000-points-per-hour global quota shared across apps, plus per-endpoint burst limits (typically 100 GET requests/second). API token-based traffic continues to be governed by the existing burst limits rather than the newer points-based quota.

Last verified: 2026-06-13 against the sources listed below.

Sources:

• Manage API tokens for your Atlassian account — Atlassian Support
• Basic auth for REST APIs — Atlassian Developer
• OAuth 2.0 (3LO) apps — Atlassian Developer
• Rate limiting — Atlassian Developer

‍