This page shows you how REST clients can authenticate themselves using basic authentication with an Atlassian account email address and API token. Authentication using passwords has been deprecated.
Basic authentication is not as secure as other methods. We recommend using it for simple scripts and manual calls to the REST APIs. Otherwise, consider building an app:
The Jira REST API is protected by the same restrictions that apply in the standard Jira web interface. These restrictions mean that if you don't log in, you access Jira anonymously. If you log in and don't have permission to view something in Jira, you won't be able to view it using the Jira REST API either.
In most cases, the first step in using the Jira REST API is to authenticate a user account with your Jira site. This page provides a simple example of basic authentication.
Basic auth requires API tokens. You generate an API token for your Atlassian account and use it to authenticate anywhere where you would have used a password. This enhances security because:
See the Atlassian Cloud Support API tokens article to discover how to generate an API token.
Most client software provides a simple mechanism for supplying a user name (in our case, the email address)
and API token that the client uses to build the required authentication headers. For example, you can
specify the -u
argument in cURL as follows:
1 2curl -D- \ -u fred@example.com:freds_api_token \ -X GET \ -H "Content-Type: application/json" \ https://your-domain.atlassian.net/rest/api/2/issue/createmeta
You can construct and send basic auth headers. To do this you perform the following steps:
useremail:api_token
.1 2echo -n user@example.com:api_token_string | base64
1 2$Text = ‘user@example.com:api_token_string’ $Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text) $EncodedText = [Convert]::ToBase64String($Bytes) $EncodedText
Authorization
header with content Basic
followed by the encoded string. For example, the string fred:fred
encodes to ZnJlZDpmcmVk
in base64, so you would make the request as follows:1 2curl -D- \ -X GET \ -H "Authorization: Basic ZnJlZDpmcmVk" \ -H "Content-Type: application/json" \ "https://your-domain.atlassian.net/rest/api/2/issue/QA-31"
Because Jira permits a default level of access to anonymous users, it does not supply an authentication challenge. Some HTTP clients expect to receive an authentication challenge before they send an authorization header. This means that a client may not behave as expected. In this case, configure the client to supply the authorization header, as described above, rather than relying on its default mechanism.
A CAPTCHA is 'triggered' after several consecutive failed log in attempts, and requires the user to interpret a distorted picture of a word and type that word into a text field with each subsequent log in attempt. If CAPTCHA has been triggered, you cannot use Jira's REST API to authenticate with the Jira site.
You can check this in the error response from Jira. If there is an X-Seraph-LoginReason
header with
a value of AUTHENTICATION_DENIED
, the application rejected the login without even checking the password.
This is the most common indication that Jira's CAPTCHA feature has been triggered.
Rate this page: