# Jira authentication options

SpecSync supports several authentication options for the [supported Jira systems](/specsync/jira/reference/compatibility.md#supported-server-systems). This section provides a summary of how the different authentication options have to be configured:

For Jira Cloud:

* [API Token](#jira-api-token)

For Jira Server or Data Center:

* [Personal access tokens](#jira-personal-access-tokens)
* [User name and password](#jira-user-name-and-password)

The authentication credentials can be specified in multiple ways:

1. During the execution of the SpecSync command using the interactive prompt (password is masked). This method is used by SpecSync if either the user name (token) or the password is not configured anywhere else.
2. Using the `--user` and `--password` [command line options](/specsync/jira/reference/command-line-reference.md#common-command-line-options).
3. In the [`remote` section](/specsync/jira/reference/configuration/configuration-remote.md) of the [SpecSync configuration file](/specsync/jira/features/general-features/configuration-file.md) (`specsync.json`).
4. In the [user-specific configuration file](/specsync/jira/features/general-features/hierarchical-configuration-files.md#user-specific-configuration-files).
5. In system environment variables that can be referred to either in the configuration file or from the command prompt (see examples below). The environment variable name has to be specified using the `{env:ENV_VAR}` format (`%ENV_VAR%` format is also accepted for backwards compatibility).

### Examples

Specifying the user name in the `specsync.json` configuration file:

{% code title="specsync.json" %}

```javascript
{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "account01"
  },
  ...
}
```

{% endcode %}

Specifying the user name in the command line:

```
dotnet specsync push --user "account01"
```

A [user-specific configuration file](/specsync/jira/features/general-features/hierarchical-configuration-files.md#user-specific-configuration-files) that configures credentials for multiple projects.

{% code title="specsync.json (in C:\Users\my\_user\AppData\SpecSync folder)" %}

```javascript
{
  "$schema": "http://schemas.specsolutions.eu/specsync-user-config-latest.json",

  "knownRemotes": [
    {
      "projectUrl": "https://dev.azure.com/myorg/*",
      "user": "g2x.....................ac2vx57i4a"
    },
    {
      "projectUrl": "https://dev.azure.com/otherorg/OtherProject",
      "user": "y6s.....................ksuc7tsts"
    }
  ]
}
```

{% endcode %}

Specifying the user credentials that refer to an environment variable in the `specsync.json` configuration file. The example requires the user name to be stored in the environment variable `SPECSYNC_REMOTE_USER`:

{% code title="specsync.json" %}

```javascript
{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "{env:SPECSYNC_REMOTE_USER}"
  },
  ...
}
```

{% endcode %}

You can also use the environment variables without the shell resolving their values. For that, specify the value in the `{env:ENV_VAR}` format.

```
dotnet specsync push --user "{env:SPECSYNC_REMOTE_USER}"
```

## Permissions required for users used by SpecSync <a href="#jira-required-permissions" id="jira-required-permissions"></a>

SpecSync creates and manages Test Cases in Jira. Therefore to be able to operate it needs to have

* read/write access for the Test Case issue type
* read access for other issue types the Test Cases are linked to.

More specifically, the following *Project permissions* are required:

* Browse Projects
* View Read-Only Workflow

The following *Issue permissions* are required:

* Assign Issues (only if you plan to update the assigned to field)
* Close Issues (only if you plan to update the issue state field)
* Create Issues
* Edit Issues
* Link Issues
* Modify Reporter (only if you plan to update the related field)
* Resolve Issues (only if you plan to update the issue state field)
* Schedule Issues (only if you plan to update the due date field)
* Transition Issues (only if you plan to update the issue state field)

The following *Comments permissions* are required:

* Add Comments

The following *Attachments permissions* are required:

* Create Attachments

## Jira API Token <a href="#jira-api-token" id="jira-api-token"></a>

In order to connect to **Jira Cloud** with SpecSync, you can authenticate yourself with Jira API tokens. For that you need to create an API Token in Jira Cloud (see [instructions](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)) and then specify your email address as user name and the token as password.

The following example authenticates using the email address `account01@mycompany.com` and API token `Kyu4Wl3twFAa9cAWklTCB476`

{% code title="specsync.json" %}

```javascript
{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "account01@mycompany.com",
    "password": "Kyu4Wl3twFAa9cAWklTCB476"
  },
  ...
}
```

{% endcode %}

## Personal access tokens <a href="#jira-personal-access-tokens" id="jira-personal-access-tokens"></a>

In order to connect to **Jira Server** or **Jira DataCenter** with SpecSync, you can authenticate yourself with Personal Access Tokens (PAT). For that you need to create a PAT in Jira Server (see instructions in the section "Creating PATs in the application" of the [Jira Documentation page](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)) and then use that as user name without specifying a password.

The following example authenticates using the PAT `AGT2OTk3NjMxNDQyOlBfg4kDgqKreys6v0FzrcDBZR89`

{% code title="specsync.json" %}

```javascript
{
  ...
 "remote": {
    "serverUrl": "http://myjiraserver:9090/",
    "project": "MyCalculator",
    "user": "AGT2OTk3NjMxNDQyOlBfg4kDgqKreys6v0FzrcDBZR89"
  },
  ...
}
```

{% endcode %}

## User name and password <a href="#jira-user-name-and-password" id="jira-user-name-and-password"></a>

In order to connect to **Jira Server** or **Jira DataCenter** with SpecSync, you can authenticate yourself with user name and password.

It is not recommended to include the password to the configuration file. If you don't specify your password, SpecSync will ask for it using an interactive prompt. Alternatively you can consider using [personal access tokens](#jira-personal-access-tokens) or environment variables.

The following example specifies the user name `account01` in the configuration file.

{% code title="specsync.json" %}

```javascript
{
  ...
  "remote": {
    "serverUrl": "http://myjiraserver:9090/",
    "project": "MyCalculator",
    "user": "account01"
  },
  ...
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.specsolutions.eu/specsync/jira/features/general-features/server-authentication-options.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.