What we need

[] API Token [] Username [] Jira Subdomain (e.g., your-company.atlassian.net) [] Atlassian Org ID (found in Atlassian Admin Console). In the Admin console url, it looks like https://admin.atlassian.com/o/{ORG ID HERE!}/profile

Follow these steps to generate a Jira API token for accessing Jira issues and users on Jira Cloud:

Prerequisites

User Permissions Prerequisites

The Confluence user that will be used for integration (whether a newly created one or existing one) needs these permissions:

1. Global permission: Administer Confluence -> https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/
2. Project permission: Browse Projects -> https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/

Orgwide considerations

1. All User Emails are set to Visible: Ensure all users have their email marked as visible by “Anyone”. This is set up by the user in their Atlassian account settings, in Profile and visibility and the subsection Contac.

Steps

1. Log in to your Atlassian account

   • Visit the Atlassian account management page.
   • Sign in with your Atlassian account credentials.

2. Create an API token

   • Click on Create API token.
   • Enter a meaningful label for your token (e.g., “Parable Integration”).
   • Click Create.

3. Copy and secure your token

   • Once generated, copy the token value.
   • Store it securely. This token cannot be viewed again after you close the dialog.

4. Use the token with Basic Authentication

   • The token is used with Basic Authentication in the following format:
   • Your email address is the username
   • The API token is the password

If you’d like more indepth documentation on create an API token and integrating with Confluence REST API, here is their documentation: https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/

You can use this token with the following Python function:

def jira_authentication_token(email = None, token=None):
    credentials = f"{email or os.environ['EMAIL']}:{token or os.environ['TOKEN']}"
    return base64.b64encode(credentials.encode('utf-8')).decode('utf-8')

This function encodes your email and token in the format required for the Authorization header:

Authorization: Basic BASE64_ENCODED_CREDENTIALS

Permissions

The API token grants access based on your Jira user permissions. For Jira Cloud, the key API endpoints include:

• /rest/api/3/search/jql — Search for issues using JQL (Jira Query Language)
• /rest/api/3/project/search — Search for projects
• /rest/api/3/users — Get user information
• /rest/api/2/auditing/record — Get auditing records (requires Jira Administrator permission)

Permissions to request

• BROWSE_PROJECTS - to see issues in a project
• ADMINISTER - for audit log (not implemented)

Item Checklist of what’s needed for integration

1. Your Atlassian account email address
2. Jira API token
3. Jira Cloud instance URL (e.g., your-company.atlassian.net)

Required Permissions

To use the Jira Cloud API effectively, your Jira user account should have:

• Browse projects permission: BROWSE_PROJECTS
• View issues permission (included with BROWSE_PROJECTS)
• For auditing records and seeing Users: Jira Administrator permission (ADMINISTER)