An API token allows Hevo to authenticate with your Jira Cloud site using your Atlassian account when you use the Basic authentication method. Atlassian has deprecated the use of account passwords for basic authentication with its REST APIs, so you must use an API token instead.

Perform the following steps to obtain the API token:

1. Log in to your Atlassian account as the user whose account you want Hevo to connect with.

2. On the API Tokens page, click Create API token.

   

   Note: Hevo does not support API tokens with scopes, as Atlassian accepts these tokens only through its API gateway URL. Do not use the Create API token with scopes option.

3. In the Create an API token dialog, do the following:

   

   1. Specify the following:

      • Name: A unique name to identify the API token. For example, hevo-jira-cloud-doc-test.

      • Expires on: The date on which the API token expires. You can select a date from one day up to one year from the current date. Default value: One week from the current date.

        Note: After the token expires, Hevo cannot ingest data until you create a new token and update it in your Source configuration.

   2. Click Create.

4. In the Copy your API token dialog, click Copy to copy the API token, and save it securely like any other password.

   

   Note: Atlassian displays the API token only once. After you close the Copy your API token dialog, the API token cannot be retrieved. If the API token is lost, you must create a new one and modify the Source configuration in the Pipeline with the new API token.

You can now view the newly created API token on the API Tokens page. Use this API token, along with the email address of your Atlassian account, while configuring your Jira Cloud Source in the Pipeline.

A service account is an Atlassian account that is not associated with a person. To use the Service Account authentication method, you must give a service account access to Jira and create an OAuth 2.0 credential for it. The credential provides the client ID and client secret that Hevo uses to connect to your Jira Cloud site.

Note: You must log in as an organization admin to perform these steps.

Perform the following steps to obtain the service account credentials:

1. Log in to Atlassian Administration and select your organization.

   

2. In the left navigation pane, click Directory, and then click Service accounts.

   

3. On the Service accounts page, do one of the following:

   • To use an existing service account, click the service account that you want Hevo to use.

   • To create a service account, perform the following steps:

     1. Click Create a service account.

        

     2. On the Name service account page, do the following:

        

        1. Specify the following:

           • Name: A unique name for the service account, between 6 and 30 characters. For example, hevo-jira-doc-test.

           • Description: A suitable text to describe the purpose of the service account.

        2. Click Next.

     3. On the Select app roles page, do the following:

        

        1. From the Roles drop-down for each of the following apps on your site, select the corresponding role:

           App	Role	Required for
           Jira	User	Projects, issues, and the other Jira objects. This role is mandatory.
           Jira Administration	App admin	The objects that require the Administer Jira global permission, such as project_role and security_scheme.
           Jira Service Management	User (agent)	The Jira Service Management objects, such as request and sla.
           Assets	User	The Assets objects.

           Note: If an app is not listed for your site, skip it. Hevo marks the objects that require the app as Inaccessible.

        2. Click Create.

           You are redirected to the page of the newly created service account.

4. On the <Your Service Account Name> page, click Create credentials.

   

5. On the Choose authentication type page, select OAuth 2.0, and then click Next.

   

6. On the Name your OAuth credentials page, specify a unique Name for the credential, and then click Next.

   

7. On the Select scopes page, do the following:

   

   1. Search for and select the check box next to each of the following scopes:

      Category	Scope	Description
      Jira platform	read:jira-work	Read project and issue data, including attachments, comments, and worklogs. This scope is mandatory.
      	read:jira-user	Read user information, such as names and email addresses.
      	manage:jira-configuration	Read Jira configuration data, such as statuses, project roles, and permission schemes.
      	manage:jira-project	Read issue security schemes and their security levels.
      	read:issue-details:jira	Read issue details, which Hevo requires to search for issues and to read the issues on boards.
      	read:project:jira	Read projects, which Hevo requires to read boards and the projects linked to them.
      Jira Software	read:board-scope:jira-software	Read boards and the issues on them.
      	read:board-scope.admin:jira-software	Read board configuration, such as board filters and properties.
      	read:epic:jira-software	Read epics and the issues related to them.
      	read:sprint:jira-software	Read sprints and the issues in them.
      Jira Service Management	read:servicedesk-request	Read customer requests, including approvals, comments, and request types.
      Assets	read:cmdb-object:jira	Read Assets objects and their attribute values.
      	read:cmdb-schema:jira	Read Assets object schemas.
      	read:cmdb-type:jira	Read Assets object types.
      	read:cmdb-attribute:jira	Read the attributes of Assets object types.

      Note: If a scope other than read:jira-work is not granted, Hevo cannot ingest data for the objects that require it. Although the manage:jira-configuration and manage:jira-project scopes allow write access, Hevo uses them only to read data from your Jira Cloud site.

   2. Click Next.

8. On the Review your OAuth credential information page, verify the name and scopes of the credential, and then click Create.

   

9. On the Your OAuth credential page, click the Copy icon next to Client ID and Client secret to copy them, and save them securely like any other password.

   

   Note: Atlassian displays the client ID and client secret only once. After you leave the Your OAuth credential page, they cannot be retrieved. If the credentials are lost, you must create a new OAuth 2.0 credential and modify the Source configuration in the Pipeline with the new credentials.

You now have the client ID and client secret of the OAuth 2.0 credential. Use them while configuring your Jira Cloud Source in the Pipeline.