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

To get a Jira API token, log in to your Atlassian account security settings at id.atlassian.com/manage-profile/security/api-tokens. Select the option to create a token with scopes, set an expiration date of up to one year, and copy the value immediately to a secure location. You use this token as the password in HTTP Basic Authentication, paired with your Atlassian account email address, to authenticate requests to the Jira Cloud REST API.

Understanding how to get Jira API token access is the first step in connecting your custom applications to Jira. The following sections detail the process to create Jira API token credentials, compare scoped and unscoped tokens with OAuth 2.0, explain where the credential goes in your HTTP request, and outline how to resolve common authorization errors.

Prerequisites

Before you can generate a token, you need an active Atlassian account with access to the Jira Cloud site you want to call. Your Jira site URL typically follows the format https://your-domain.atlassian.net.

Your account’s login method affects the token creation process. Having two-step verification or single sign-on (SSO) enabled does not prevent you from generating credentials. However, if you log in with a standard password or use a third-party login provider, Atlassian enforces an additional security check. They email you a one-time passcode to verify your identity before you can view the security page, create new credentials, or manage existing tokens.

You also need a basic understanding of HTTP headers to test the credential once it is generated. If you are integrating multiple systems and need credentials for other platforms, you might also need to learn how to get a GitHub personal access token step by step to connect your version control systems.

Step-by-step: creating a Jira API token

Follow these exact steps to generate your authentication string:

1. Log in to id.atlassian.com/manage-profile/security/api-tokens. You may need to enter a one-time passcode sent to your email.
2. Select the Create API token with scopes button for a restricted credential. Alternatively, select Create API token if you need an unscoped token.
3. Give the token a descriptive name that identifies its exact purpose or the system using it, such as jira-sync-prod. If your internal documentation asks you to generate a Jira API key, note that Atlassian officially refers to this credential as an API token in their interface.
4. Set an expiration date. According to Atlassian Support, after December 15, 2024, new API tokens expire in one year by default, and you can set the expiration date to be from one day up to one year.
5. Select Create to generate the string.
6. Copy the value immediately. According to Atlassian Support, you cannot recover the API token after you are done with this step and they recommend you save your API token in a password manager. If you lose the value, you must revoke it and start over.

If you manage support systems alongside project management tools, the authentication process differs by platform. For example, you might need to enable API token access in Zendesk Admin Center to generate an API token and call the Zendesk API with Basic auth for support tickets.

API Token vs. OAuth 2.0

Jira provides different authentication methods depending on the architecture of your integration.

Unscoped Tokens: These inherit the full permission set of the specific Atlassian account that created them. They are simple to implement but grant broad access, meaning any action the user can perform in the Jira interface can also be performed via the API.

Scoped Tokens: These limit access to specific permissions, such as read:jira-work for reading issues or write:jira-work to modify them. They follow the principle of least privilege.

OAuth 2.0 (3LO): This method lets an application act on behalf of other Jira users rather than just your own account. Instead of a static token, the app directs users through a consent screen. It then issues a short-lived Jira access token and a rotating refresh token.

Use an API token for personal scripts, command-line tools, and internal automation where you only need your own access level. Use OAuth 2.0 (3LO) for customer-facing applications that multiple external Jira users will install.

Where the credential goes

Jira Cloud’s REST API requires HTTP Basic Authentication. You format the request header using your Atlassian account email address as the username and the API token as the password.

The HTTP standard requires this string to be base64-encoded. Most HTTP clients handle this encoding for you automatically. For example, when using cURL, you pass the email and token using the -u flag (-u email@example.com:api_token).

The base URL you call depends on the type of token you created. Unscoped tokens use your standard site URL (https://your-domain.atlassian.net). Scoped tokens route through a centralized API gateway. According to Atlassian Support, you need to call the Atlassian API to use API tokens with scopes for Jira using the structure https://api.atlassian.com/ex/jira/{cloudId}.

Minimal working example

The following code provides a cURL example for a basic GET request using the Jira API token. According to One, to test connection in Jira, send a GET request to https://api.atlassian.com/ex/jira/{jiraCloudId}/rest/api/3/myself. This returns details for the current authenticated Jira user.

curl -X GET "https://api.atlassian.com/ex/jira/{jiraCloudId}/rest/api/3/myself" \
  -u "user@example.com:YOUR_API_TOKEN"

You can also script this request. This snippet provides a Node.js example for a basic GET request using the Jira API token to call the exact same endpoint.

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

const response = await fetch(
  `https://api.atlassian.com/ex/jira/${process.env.JIRA_CLOUD_ID}/rest/api/3/myself`,
  {
    method: "GET",
    headers: {
      Authorization: `Basic ${auth}`
    }
  }
);

const data = await response.json();
console.log(data);

Store your email, token, and cloud ID safely in environment variables. For more practical code, read our guide to building a Jira API integration.

Common errors and fixes

Authentication failures usually result from expired credentials or mismatched formatting.

Why am I getting a 401 Unauthorized?
This response indicates that the email and token pair is wrong, the token has expired, or the credential was revoked from the security settings page. Verify that you are passing the Atlassian account email address as the Basic Authentication username, rather than a display name or local username.

Why does my request fail with an X-Seraph-LoginReason: AUTHENTICATION_DENIED header?
Jira triggers a CAPTCHA challenge after consecutive failed login attempts. Because the REST API cannot complete a visual CAPTCHA challenge, this header means the login was rejected before the password was even checked. Log in to the Jira web interface in a browser once to clear the CAPTCHA, then retry the API call.

Why does refreshing my OAuth token return 403 invalid_grant?
If you use OAuth 2.0 (3LO), this error means the refresh token is unknown or invalid. This happens because the user changed their Atlassian password, the refresh token expired after 90 days of inactivity, or your application failed to store the new rotating refresh token from the previous exchange. The user must complete the full authorization flow again to generate new credentials.

The faster way with Knit

With Knit: Managing individual API tokens, scoped base URLs, and distinct pagination logic across different tools requires constant maintenance. For teams connecting many tools, Jira integrates via Knit’s Unified Ticketing API alongside other platforms to standardize this process.

Instead of building custom authentication logic for Jira, Knit handles the routing and token management. You authenticate your application against the Knit base URL (https://api.getknit.dev/v1.0) using standard HTTP headers: Authorization: Bearer <YOUR_KNIT_API_KEY> and X-Knit-Integration-Id: <...>.

Knit provides endpoints like GET /ticketing/account, GET /ticketing/accounts, GET /ticketing/collections, GET /ticketing/contact, GET /ticketing/contacts, GET /ticketing/group, GET /ticketing/groups, and GET /ticketing/tags. For example, calling GET /ticketing/accounts returns a standardized JSON response containing an array of accounts, complete with consistent fields like data.accounts[].id, data.accounts[].name, data.accounts[].createdAt, data.accounts[].website, and data.accounts[].industry. The response handles pagination cleanly through data.pagination.next and data.pagination.previous fields, removing the need to parse Jira-specific offset logic.

Frequently Asked Questions

Users often encounter specific limits and naming conventions when working with Atlassian credentials.

Where do I find my Jira API token after creating it?
You can only view the string immediately after you click the create button. Existing credentials listed on the security page only show names, scopes, and expiration dates. If you lose the value, revoke the old token and create a new one.

What is the difference between a Jira API token and a Jira API key?
They are the exact same credential. While developers often search for a Jira API key when building scripts, Atlassian officially uses the term "API token" in its documentation and security interface. Both terms refer to the string you generate to use as a password for HTTP Basic Authentication.

What’s the difference between a Jira API token and OAuth 2.0 (3LO)?
An API token authenticates as you via HTTP Basic Authentication, which is simple but tied to one specific Atlassian account. OAuth 2.0 (3LO) lets an application act on behalf of other users after they grant consent through an authorization screen, issuing short-lived access tokens and rotating refresh tokens. Use a token for personal scripts and internal automation, and use OAuth 2.0 (3LO) for an application that multiple Jira users will install.

Do Jira API tokens expire?
Yes, they expire. According to Atlassian Support, after December 15, 2024, new API tokens expire in one year by default. You can change this duration to anywhere from one day up to one year during the creation process. Once the expiration date passes, the credential stops working immediately. There is no automatic renewal mechanism, so you must generate Jira API token replacements before the deadline and update your integrations.

Why do I need my site’s cloudId for some Jira API calls?
Scoped API tokens and OAuth 2.0 (3LO) applications both route requests through a centralized API gateway (api.atlassian.com) rather than your specific Jira site domain (your-domain.atlassian.net). The cloudId specifies which Jira Cloud instance the gateway should forward the request to.

Is the Jira API free to use with an API token?
Yes, generating a credential and calling the Jira Cloud REST API costs nothing beyond your existing Atlassian subscription tier. Usage is governed by Jira’s rate limits, which include a global points-per-hour quota and specific endpoint burst limits.