Jira API Access Tokens: A Step-by-Step Setup Guide [2026]

Struggling with Jira 401 errors? Learn to create and secure a jira api access token step by step—click to set up safely in 2026.

Jira automation often breaks for one simple reason: the API credential was created incorrectly, placed in the wrong request format, or left exposed where anyone can copy it. A small setup mistake can produce confusing 401 errors, failed scripts, and hours of unnecessary troubleshooting.

The risk grows when you reuse one credential across several integrations. A leaked token may let someone read project details, update issues, or trigger workflow actions under your account. But here's the truth: creating a Jira API access token is straightforward when you follow the right sequence.

This guide shows you how to create, test, secure, rotate, and revoke a token in 2026. You’ll also learn how authentication differs between Jira Cloud and Jira Data Center, when to use OAuth, and how to troubleshoot common failures.

How to Create and Use a Jira API Access Token

A Jira API access token is a secret credential that lets an application or script authenticate to Jira through its REST API. In Jira Cloud, you typically use the token with your Atlassian account email through basic authentication.

The fastest setup is: create the token, combine it with your Atlassian email, encode the pair for basic authentication, and send it with an API request. Keep the token private because it can act with the permissions assigned to your account.

Jira product screenshot

Step 1: Confirm Your Jira Hosting Type

First, identify whether your Jira site runs on Atlassian Cloud or Jira Data Center. The token process differs between these environments.

Jira Cloud: Create an API token through your Atlassian account security settings.
Jira Data Center: Your administrator may enable personal access tokens through the Jira profile area.
OAuth integrations: Use OAuth when several people need access, when an external application acts independently, or when you need user consent and scoped permissions.

A Jira Cloud address commonly looks like your-team.atlassian.net. A self-managed Jira deployment may use a company-owned domain or an internal network address.

Step 2: Open Atlassian Security Settings

For Jira Cloud, sign in with the Atlassian account connected to your Jira site. Then open your account security settings and find the area for API tokens.

You can usually reach it through the Atlassian account management page. If the menu has changed, search the account settings for API tokens or security credentials.

Step 3: Create a New Token

Choose the option to create an API token. Add a clear label that tells you where the credential is used.

For example, use labels such as:

marketing-reporting-2026
ci-jira-status-updates
local-issue-export-test

Choose an expiration period when Atlassian presents that option. A short lifetime reduces exposure if the credential is accidentally revealed.

After creation, copy the token immediately. Atlassian may show the full value only once. Store it in a protected secrets manager or environment variable rather than placing it directly inside application code.

Step 4: Pair the Token With Your Atlassian Email

Jira Cloud basic authentication uses your Atlassian account email as the username and the API token as the password.

The credential pair looks like this:

your-email@example.com:your-api-token

For an HTTP request, the pair is normally encoded as Base64. Base64 is an encoding method, not encryption, so always send the request over HTTPS.

Step 5: Test Authentication With a Safe Endpoint

Start with an endpoint that reads your account details. This confirms authentication without changing a Jira issue.

curl --request GET \
  --url "https://your-domain.atlassian.net/rest/api/3/myself" \
  --user "your-email@example.com:your-api-token" \
  --header "Accept: application/json"

With valid credentials, Jira should return account information in JSON format. The exact fields can vary according to your account privacy settings and Jira configuration.

Step 6: Move the Secret Into an Environment Variable

Do not keep a live token inside a script that you share with colleagues or publish to a public code repository. Use environment variables during local testing.

export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

Then reference the variables in your command:

curl --request GET \
  --url "https://your-domain.atlassian.net/rest/api/3/myself" \
  --user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --header "Accept: application/json"

For production, use your company’s approved secrets manager. Give the integration only the account permissions it genuinely needs.

Step 7: Test a Controlled Jira Action

After the read-only test succeeds, try a limited action in a test project. For example, retrieve issues from a known project before attempting updates.

curl --request GET \
  --url "https://your-domain.atlassian.net/rest/api/3/search?jql=project=TEST" \
  --user "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --header "Accept: application/json"

When an integration must update issues, test one clearly identified issue first. Check the result in Jira before allowing a larger batch operation.

Step 8: Record Ownership and Rotation Details

Record who owns the integration, where the token is used, its creation date, and its planned replacement date. Avoid putting the actual secret in that record.

A simple ownership note can include:

Integration name
Jira site
Account responsible for the token
Systems that consume it
Required Jira permissions
Rotation deadline
Revocation procedure

How Jira API Authentication Works

Jira receives an HTTP request containing an authentication credential. It checks the credential, identifies the account, and evaluates that account’s Jira permissions before returning a response.

For Jira Cloud, the common pattern is email plus API token through basic authentication. The token replaces your Atlassian account password for API requests, but it does not grant more Jira permissions than your account already has.

Authentication Versus Authorization

Authentication answers, “Who is making this request?” Authorization answers, “What is that account allowed to do?”

For example, a valid token may authenticate successfully while an issue update still returns a permission error. The account may lack browse, edit, transition, or project administration rights.

Common Authentication Methods

Method	Typical use
API token with email	Jira Cloud scripts and simple integrations
Personal access token	Jira Data Center integrations tied to one account
OAuth 2.0	Multi-account applications and consent-based integrations
OAuth 1.0a	Some legacy Jira integrations requiring signed requests

Choose the least complex method that fits your integration. A short internal script may work well with an API token, while a customer-facing application usually needs OAuth.

Cloud and Data Center Token Differences

Jira Cloud and Jira Data Center do not share an identical credential workflow. Confusing them is one of the quickest ways to receive an authentication error.

Jira Cloud commonly uses an Atlassian account email and API token. Jira Data Center may offer personal access tokens through your profile, depending on the Jira version and administrator settings.

Jira Cloud Example

A Jira Cloud request generally uses this pattern:

curl --user "email@example.com:API_TOKEN" \
  --header "Accept: application/json" \
  "https://company.atlassian.net/rest/api/3/myself"

The domain, API version, and permissions must match your Jira Cloud configuration. Some endpoints require specific scopes or project permissions.

Jira Data Center Example

In Jira Data Center, an administrator may enable personal access tokens. The request often uses a bearer token header:

curl --request GET \
  --url "https://jira.example.com/rest/api/2/myself" \
  --header "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  --header "Accept: application/json"

Exact behavior can differ by Jira release and administrator settings. Check your internal Jira administration guidance before selecting a header format.

Why the Difference Matters

A Cloud API token sent as a bearer token may fail. A Data Center personal access token sent as an email-and-password pair may also fail.

Here's why: the credential type determines how Jira expects the request to be structured. Confirm the hosting model before changing code or rotating credentials.

Secure Handling and Rotation Practices

A token should be treated like a password with a clearly defined owner. Anyone who obtains it may be able to perform actions as the associated Jira account.

Keep Credentials Out of Code

Use environment variables, a secrets manager, or your CI/CD platform’s protected secret settings. Avoid placing tokens in source code, shell history, screenshots, tickets, or chat messages.

If a token appears in a public repository, assume it has been exposed. Revoke it immediately and create a replacement.

Use Separate Tokens for Separate Purposes

Do not use one token for every script. Create separate credentials for reporting, deployment automation, testing, and local development.

For example, revoking a reporting token should not stop a deployment pipeline. Separate credentials reduce the impact of one mistake.

Limit Account Permissions

API tokens inherit the permissions of their associated account. Create or select an account with only the project access required by the integration.

An issue-reporting script usually needs browse permission. It may not need permission to delete issues, edit workflows, or administer projects.

Rotate Before Expiration

Plan token rotation before the credential reaches its expiration date. Create the replacement, update the integration, test it, and then revoke the old token.

For a production service, use a short overlap period. This allows you to confirm the replacement works before removing the previous credential.

Troubleshooting API Token Errors

Most Jira authentication failures fall into a few recognizable categories. Start with the HTTP status code, then inspect the request format and account permissions.

Response	Likely cause	Recommended check
401 Unauthorized	Invalid, expired, revoked, or incorrectly formatted credential	Check the email, token, authentication method, and Jira domain
403 Forbidden	Authentication succeeded, but the account lacks permission	Review project roles, issue permissions, and API scopes
404 Not Found	Incorrect endpoint, project key, or inaccessible resource	Confirm the URL and whether the account can browse the item
429 Too Many Requests	Rate limit reached	Slow requests and honor the response retry guidance

Check the Email Address

For Jira Cloud, the email must match the Atlassian account associated with the token. A personal email and a company email may belong to different accounts.

Check Hidden Characters

Copying a token can add spaces or line breaks. Re-enter the value carefully or create a replacement token if you cannot confirm its integrity.

Check the API Version

Jira Cloud commonly supports REST API version 3, while many Data Center installations use version 2. The correct endpoint depends on your Jira environment and release.

Check Permissions Separately

Test /myself first. If that works, authentication is probably valid. Then test a read request against a project the account can access.

When the read request works but an update fails, focus on Jira permissions rather than the token itself.

Jira API Token Alternative: ONES.com

ONES.com product screenshot

Value Proposition

ONES.com is a unified platform for project management and knowledge management. If your team wants Jira-compatible workflows with built-in reporting and flexible deployment, ONES Project offers a Jira alternative without requiring a large plugin stack.

ONES Project and ONES Wiki are sold separately, allowing you to choose project management, knowledge management, or both.

Core Capabilities

Plugin-heavy Jira setup → Jira-compatible workflows → Keep familiar issue, sprint, and workflow patterns while reducing dependence on add-ons.
Unclear delivery progress → Built-in reporting → Give project leads clearer visibility into status, workload, and progress.
Rigid issue structures → Custom workflows and fields → Adapt project tracking to your team’s review stages, classifications, and operating rules.
Manual sprint administration → Sprint management → Plan, track, and review sprint work in one project environment.
Repeated routine actions → Automation → Reduce manual updates for transitions, notifications, and recurring project events.
Concern about hosting restrictions → Four deployment options → Choose Cloud, On-Premise, Private Cloud, or Air-gapped deployment.
Migration concerns → Full feature parity → Use the same broad feature set across cloud and self-hosted versions.
Separate project and knowledge workflows → ONES.com platform → Connect project execution with knowledge management when your team needs both products.

Application Scenarios

Regulated engineering team: A team working under strict network controls can use an air-gapped deployment. Project workflows remain available without sending operational activity outside the restricted environment.

Growing software team: A team moving beyond basic issue tracking can configure custom fields, sprint workflows, automation, and reporting without assembling every function through separate plugins.

Distributed product organization: Product, engineering, and support teams can use project workflows for delivery while maintaining a connected knowledge environment through ONES Wiki.

Common Challenges

Challenge: The Token Works Locally but Fails in Production

Cause: The production service may not receive the environment variable, or its secret value may contain an unintended character.

Solution: Confirm that the deployment platform exposes the expected variable name. Test the credential with a safe endpoint and rotate it if the value appeared in logs.

Challenge: A Valid Token Returns a Permission Error

Cause: The account can authenticate but lacks access to the project, issue, transition, or action.

Solution: Review project roles, issue security, workflow conditions, and global permissions. Do not create a more powerful token unless the integration genuinely needs broader access.

Challenge: A Token Was Accidentally Exposed

Cause: The secret appeared in a code repository, terminal history, screenshot, or support message.

Solution: Revoke the token immediately. Review recent activity, create a replacement, update the integration, and remove the exposed value from accessible locations.

Challenge: Rotation Interrupts Automation

Cause: The old credential was revoked before every service had switched to the new one.

Solution: Create the replacement first, update each consumer, run a controlled test, and revoke the old credential only after successful verification.

FAQs

Is a Jira API token the same as my Jira password?

No. A Jira Cloud API token is a separate credential used for API authentication. Your script normally sends your Atlassian email as the username and the token as the password for basic authentication. You can revoke the token without changing your normal sign-in password. Treat the token as highly sensitive because it may allow actions under your account’s Jira permissions.

Where do I create a Jira Cloud API token?

Sign in to the Atlassian account connected to your Jira Cloud site. Open account security settings and locate the API token area. Create a labeled token, choose an expiration period if available, and copy the value immediately. Atlassian may not display the complete token again, so store it in an approved secrets manager or protected environment variable.

Why am I receiving a 401 response?

A 401 response usually means Jira could not validate the credential. Check the Atlassian email, token value, Jira domain, and authentication format. Confirm that the token has not expired or been revoked. Also verify whether you are connecting to Jira Cloud or Data Center, because the expected authentication method may differ between those environments.

Can I use one API token for several applications?

You can, but separate tokens are safer. A dedicated token for each integration makes ownership, monitoring, rotation, and revocation easier. If one credential is exposed, you can disable that integration without interrupting unrelated services. Use the narrowest practical Jira account permissions for every token and avoid sharing credentials across teams.

Should I use OAuth instead of an API token?

OAuth is often a better fit for a multi-account application, a customer-facing integration, or a service that needs consent and scoped access. An API token is usually simpler for a controlled internal script tied to one account. Consider the number of connected accounts, permission scope, credential rotation, and whether the integration should act independently of one person.

How do I revoke a Jira API token?

Open the same Atlassian account security area where you created the token. Find the token by its label and revoke it. For Jira Data Center, use the personal access token area provided by your Jira profile if enabled. After revocation, update any service that used the credential and test the replacement through a read-only API request.

Conclusion

Creating a Jira API access token takes only a few minutes, but secure implementation requires more care. Confirm your hosting model, create the correct credential, test a harmless endpoint, and store the secret outside your code.

But here's the truth: most API problems come from small operational gaps. A wrong email, an expired token, a missing permission, or an exposed secret can disrupt an otherwise simple integration.

Use separate credentials, limit account access, rotate tokens deliberately, and revoke anything you no longer trust. If your team is also evaluating a Jira alternative, ONES.com offers Jira-compatible project workflows, reporting, automation, and flexible deployment options for different operating environments.