authentication

name	authentication
description	This skill covers all authentication methods for the Jira Cloud REST API.

Authentication Skill

This skill covers all authentication methods for the Jira Cloud REST API.

API Token Authentication (Recommended for Scripts)

Generate a token at: https://id.atlassian.com/manage-profile/security/api-tokens

Basic Auth with API Token

Jira Cloud uses your email and API token combined as Basic authentication:

# Using curl with inline encoding
curl -X GET \
  -H "Authorization: Basic $(echo -n '[e-mail]:your-api-token' | base64)" \
  -H "Accept: application/json" \
  "https://your-domain.atlassian.net/rest/api/3/myself"

# Using curl's built-in basic auth
curl -u "[e-mail]:your-api-token" \
  -H "Accept: application/json" \
  "https://your-domain.atlassian.net/rest/api/3/myself"

Environment Variables

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_USER_EMAIL="[e-mail]"
export JIRA_API_TOKEN="your-api-token"

# Then use in commands
curl -u "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "$JIRA_BASE_URL/rest/api/3/myself"

OAuth 2.0 (3LO) — For Apps and Integrations

OAuth 2.0 three-legged authorization flow for Jira Cloud:

Step 1: Register an OAuth 2.0 App

1. Go to https://developer.atlassian.com/console/myapps/
2. Create a new app
3. Add the Jira API under Permissions
4. Configure Authorization with callback URL
5. Note your Client ID and Client Secret

Step 2: Authorization URL

Redirect users to:

https://auth.atlassian.com/authorize
  ?audience=api.atlassian.com
  &client_id={YOUR_CLIENT_ID}
  &scope=read:jira-work write:jira-work manage:jira-project manage:jira-configuration
  &redirect_uri={YOUR_CALLBACK_URL}
  &state={RANDOM_STATE}
  &response_type=code
  &prompt=consent

Step 3: Exchange Code for Token

curl -X POST \
  -H "Content-Type: application/json" \
  "https://auth.atlassian.com/oauth/token" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_CALLBACK_URL"
  }'

Response:

{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "..."
}

Step 4: Get Accessible Resources

curl -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  "https://api.atlassian.com/oauth/token/accessible-resources"

Returns the cloud ID needed for API calls:

[
  {
    "id": "cloud-id-here",
    "url": "https://your-domain.atlassian.net",
    "name": "Your Site",
    "scopes": [...]
  }
]

Step 5: Make API Calls

curl -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  "https://api.atlassian.com/ex/jira/{CLOUD_ID}/rest/api/3/myself"

Step 6: Refresh Token

curl -X POST \
  -H "Content-Type: application/json" \
  "https://auth.atlassian.com/oauth/token" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

OAuth 2.0 Scopes

Scope	Description
read:jira-work	Read Jira project and issue data
write:jira-work	Create and edit issues, comments, worklogs
manage:jira-project	Create and edit projects, manage versions and components
manage:jira-configuration	Manage Jira settings, workflows, custom fields
manage:jira-data-provider	Manage data providers
read:jira-user	Read user information

Personal Access Tokens (PAT) — Data Center Only

PATs are only available in Jira Data Center, not Jira Cloud. For Cloud, use API tokens or OAuth 2.0.

Required Headers

Every API request should include:

Authorization: Basic {base64(email:token)}   # or Bearer {oauth_token}
Content-Type: application/json                # for POST/PUT requests
Accept: application/json                      # for all requests
X-Atlassian-Token: no-check                   # required for file uploads only

Security Best Practices

• Never commit API tokens or secrets to source control
• Use environment variables or secret managers for credentials
• Rotate API tokens regularly
• Use the minimum required OAuth scopes
• Implement token refresh for OAuth 2.0 integrations
• Use HTTPS for all API calls (enforced by Atlassian Cloud)
• Monitor API token usage in Atlassian admin console