You can adapt this file completely to your liking, but it should at least contain the root toctree directive.

Welcome to Atlassian Python API’s documentation!

Build status PyPI version PyPI Downloads License Codacy Badge Documentation Status

Getting started

Install package using pip:

pip install atlassian-python-api

Add a connection:

from atlassian import Jira
from atlassian import Confluence
from atlassian import Crowd
from atlassian import Bitbucket
from atlassian import ServiceDesk
from atlassian import Xray
from atlassian import AssetsCloud
from atlassian import Compass

jira = Jira(
    url='http://localhost:8080',
    username='admin',
    password='admin')

confluence = Confluence(
    url='http://localhost:8090',
    username='admin',
    password='admin')

crowd = Crowd(
    url='http://localhost:4990',
    username='app-name',
    password='app-password'
)

bitbucket = Bitbucket(
    url='http://localhost:7990',
    username='admin',
    password='admin')

service_desk = ServiceDesk(
    url='http://localhost:8080',
    username='admin',
    password='admin')

xray = Xray(
    url='http://localhost:8080',
    username='admin',
    password='admin')

Other authentication methods

Further authentication methods are available. For example OAuth can be used:

oauth_dict = {
    'access_token': 'access_token',
    'access_token_secret': 'access_token_secret',
    'consumer_key': 'consumer_key',
    'key_cert': 'key_cert'}

jira = Jira(
    url='http://localhost:8080',
    oauth=oauth_dict)

confluence = Confluence(
    url='http://localhost:8090',
    oauth=oauth_dict)

bitbucket = Bitbucket(
    url='http://localhost:7990',
    oauth=oauth_dict)

service_desk = ServiceDesk(
    url='http://localhost:8080',
    oauth=oauth_dict)

xray = Xray(
    url='http://localhost:8080',
    oauth=oauth_dict)

OAuth 2.0 is also supported:

from atlassian.bitbucket import Cloud

# token is a dictionary and must at least contain "access_token"
# and "token_type".
oauth2_dict = {
    "client_id": client_id,
    "token": token}

bitbucket_cloud = Cloud(
    oauth2=oauth2_dict)

# For a detailed example see bitbucket_oauth2.py in
# examples/bitbucket

Or Kerberos (installation with kerberos extra necessary):

jira = Jira(
    url='http://localhost:8080',
    kerberos={})

confluence = Confluence(
    url='http://localhost:8090',
    kerberos={})

bitbucket = Bitbucket(
    url='http://localhost:7990',
    kerberos={})

service_desk = ServiceDesk(
    url='http://localhost:8080',
    kerberos={})

xray = Xray(
    url='http://localhost:8080',
    kerberos={})

Or reuse cookie file:

from atlassian import utils
cookie_dict = utils.parse_cookie_file("cookie.txt")

jira = Jira(
    url='http://localhost:8080',
    cookies=cookie_dict)

confluence = Confluence(
    url='http://localhost:8090',
    cookies=cookie_dict)

bitbucket = Bitbucket(
    url='http://localhost:7990',
    cookies=cookie_dict)

service_desk = ServiceDesk(
    url='http://localhost:8080',
    cookies=cookie_dict)

xray = Xray(
    url='http://localhost:8080',
    cookies=cookie_dict)

Or using a Personal Access Token

Use token= only for Jira or Confluence Server/Data Center personal access tokens. It creates a Bearer Authorization header; it is not the authentication method for Atlassian Cloud API tokens.

First, create your access token (check https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html for details) Then, just provide the token to the constructor:

jira = Jira(
    url='https://your-jira-instance.company.com',
    token=jira_access_token
)

confluence = Confluence(
    url='https://your-confluence-instance.company.com',
    token=confluence_access_token
)

To authenticate to the Atlassian Cloud APIs Jira, Confluence, ServiceDesk:

Use the account email as username and the Cloud API token as password. Do not use token=: that parameter emits a Bearer token intended for Server/Data Center PATs and Cloud may respond with 403 Failed to parse Connect Session Auth Token. The client generates the required Basic header; do not encode email:api_token manually.

# Obtain an API token from: https://id.atlassian.com/manage-profile/security/api-tokens
# You cannot log-in with your regular password to these services.

jira = Jira(
    url='https://your-domain.atlassian.net',
    username=atlassian_username,
    password=atlassian_api_token,
    cloud=True)

confluence = Confluence(
    url='https://your-domain.atlassian.net',
    username=atlassian_username,
    password=atlassian_api_token,
    cloud=True)

# New Cloud V2 endpoints, including page retrieval, are exposed through
# the explicit versioned client. Do not base64-encode credentials yourself.
from atlassian import ConfluenceV2

confluence_v2 = ConfluenceV2(
    'https://your-domain.atlassian.net',
    username=atlassian_username,
    password=atlassian_api_token,
)
page = confluence_v2.get_page_by_id('123456789', body_format='storage')

service_desk = ServiceDesk(
    url='https://your-domain.atlassian.net',
    username=atlassian_username,
    password=atlassian_api_token,
    cloud=True)

timeout is expressed in seconds and can be increased for slow corporate networks or VPNs, for example Jira(..., timeout=120). A connection timeout means the host was unreachable in time; it is distinct from an HTTP 401/403 authentication or authorization response.

And to Bitbucket Cloud:

# Log-in with E-Mail / Username and regular password
# or with Username and App password.
# Get App password from https://bitbucket.org/account/settings/app-passwords/.
# Log-in with E-Mail and App password not possible.
# Username can be found here: https://bitbucket.org/account/settings/

from atlassian.bitbucket import Cloud

bitbucket = Cloud(
    username=bitbucket_email,
    password=bitbucket_password,
    cloud=True)

bitbucket_app_pw = Cloud(
    username=bitbucket_username,
    password=bitbucket_app_password,
    cloud=True)

Getting started with Cloud Admin module

Add a connection:

from atlassian import CloudAdminOrgs, CloudAdminUsers

cloud_admin_orgs = CloudAdminOrgs(
    admin-api-key=admin-api-key)

cloud_admin_users = CloudAdminUsers(
    admin-api-key=admin-api-key)