Atlassian API Tokens vs PATs: Authenticating a CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

API token or PAT: which does your CLI need?

If you're wiring a command-line tool into Atlassian, the short answer is this: an atlassian api token is what you create on Atlassian Cloud (the *.atlassian.net instances), and a personal access token (PAT) is the equivalent you create on Data Center or Server. They solve the same problem, authenticate a script as a user, but they live in different places and use different auth schemes. Pick the one that matches where your Jira, Confluence, or Bitbucket actually runs.

This trips people up constantly. A common thread on r/jira is someone weighing "PAT vs OAuth" for a Data Center automation user, while a Cloud user on the next thread can't find the PAT screen at all, because on Cloud there isn't one. atlassian-cli targets Atlassian Cloud, so for Jira, Confluence, and Jira Service Management you'll always reach for an API token. Bitbucket Cloud is the one product with a couple of extra options, and we'll cover those below.

What an Atlassian API token is

An Atlassian API token is a long random string tied to your Atlassian account. You pair it with your account email and the CLI sends both as HTTP Basic auth. It authenticates as you: anything you can do in Jira, Confluence, or JSM through the browser, a tool holding that token can do through the REST API.

You create one in your account security settings, not inside any single Jira or Confluence site:

1. Go to id.atlassian.com/manage-profile/security/api-tokens.
2. Click Create API token and give it a descriptive label (for example laptop-cli or ci-release-bot).
3. Copy the value immediately. Atlassian shows it exactly once, so if you lose it you create a new one.

Because the token is bound to your account and not to a single project, a leaked token is as sensitive as your password. Never paste it inline on a command line where it lands in shell history. Put it in an environment variable first:

# Load the token into a variable so it stays out of history
export ATLASSIAN_API_TOKEN="paste-your-token-here"

Where PATs and Bitbucket access tokens fit

Personal access tokens are the Data Center and Server story. On self-hosted Jira or Confluence you create a PAT from your own Profile → Personal Access Tokens inside that server, and you send it as a Bearer token rather than Basic auth. They can carry an expiry date and are the standard choice for scripts and automation users on those deployments. If your instance URL is your company's own domain instead of atlassian.net, that's the token model you're on.

Bitbucket Cloud is the interesting middle ground. It supports two current credential types, and one of them behaves a lot like a scoped PAT:

• API token (Basic auth) for your personal account. Create an Atlassian API token scoped to Bitbucket at id.atlassian.com/manage-profile/security/api-tokens and use it with your email.
• Access token (Bearer auth) scoped to a single repository, project, or workspace. Created under Settings → Access tokens on that resource, with only the scopes you grant (for example repository:read, pullrequest:write). This is the closest Cloud analog to a Data Center PAT and the right choice for CI.

Logging your CLI in

atlassian-cli stores credentials per profile, so you can keep a personal instance and a work instance side by side. The auth login command writes them once; everything after that just names a profile. Full details live in the authentication guide.

Jira, Confluence, and JSM (Cloud API token)

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

The --base-url must include https:// and no trailing slash. --default makes this the profile used whenever you omit --profile. Verify it before you trust it:

atlassian-cli auth test --profile work
atlassian-cli jira issue search --jql "project = DEV" --limit 1

Bitbucket, personal account (API token, Basic auth)

atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

Bitbucket, scoped for CI (access token, Bearer auth)

atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

Bearer auth does not need --email. Confirm the Bitbucket credential separately with atlassian-cli auth test --bitbucket --profile bb-ci. Credentials are written encrypted with AES-256-GCM to your local config directory; this project and the website never receive them.

Token types at a glance

Four credential types cover almost every atlassian-cli setup. This table maps each to where you create it, the auth scheme, and the login flag:

The pattern is consistent: Cloud user credentials use Basic auth with your email, while scoped and self-hosted tokens use Bearer auth without an email. When something returns 401, the mismatch is usually the email not matching the token owner, or a Bearer token sent where Basic was expected.

Keeping tokens out of CI logs

In CI you don't want a persisted credentials file baked into an image. atlassian-cli lets an environment variable override the stored token, so you commit only harmless profile metadata (base URL, email) and inject the real secret at run time. The token variables are checked in order:

• ATLASSIAN_CLI_TOKEN_<PROFILE>, per-profile override, profile name uppercased (e.g. ATLASSIAN_CLI_TOKEN_CI).
• ATLASSIAN_API_TOKEN, fallback used by whichever profile is active.
• For Bitbucket: ATLASSIAN_CLI_BITBUCKET_TOKEN_<PROFILE>, ATLASSIAN_BITBUCKET_TOKEN, or the shorter BITBUCKET_TOKEN.

A GitHub Actions step logs in with a throwaway profile and pulls the token from the repository secret. Because the secret is masked in logs and never written to the repo, it stays out of your history and out of the build output:

# GitHub Actions: token from a secret, profile metadata inline
- name: Query Jira
  env:
    ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
  run: |
    atlassian-cli auth login \
      --profile ci --base-url https://mycompany.atlassian.net \
      --email bot@mycompany.com --default
    atlassian-cli jira issue search --jql "project = REL" --format json

A few habits keep this tight: use a dedicated service account rather than a person's token, scope Bitbucket work to a repository or workspace access token instead of a full API token, and rotate on a schedule so a leaked value has a short shelf life. For a CI gate that only checks connectivity, atlassian-cli auth test --format quiet && echo OK exits non-zero on failure without printing anything sensitive.

How this differs from acli

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli when you want first-party vendor support; use atlassian-cli if you want a single free binary spanning Jira, Confluence, Bitbucket, and JSM with the profile-based, token-first auth model described here. The token types themselves are the same either way: they're Atlassian's credentials, and this article explains which one to create, not a proprietary scheme.

If you're comparing the two more broadly, see acli vs atlassian-cli. And if you like the idea of one credential set reaching every product, one CLI for Jira, Confluence, and Bitbucket walks through that cross-product workflow.

FAQ

Related Resources