Jira’s REST API is the mandated resource when it comes to moving data between Jira and other applications, like BI platforms, ERPs, HR tools, or anything else you’d wish to integrate, automate or pull data from.

But there’s not just one way to gain access to the Jira REST API.

Let’s have a look at the different alternatives for authentication and their security implications. That will help us better understand why you should rely on personal access tokens for use cases like no-code integration platforms.

Authentication as a Jira user

Before utilizing any of the methods included in the Jira REST API documentation for Server, remember that it’s necessary to authenticate as a user into the corresponding Jira instance.

What you can do with the API will depend on the user’s permissions: if you access as a regular user, you will be restricted to working with the data from projects where you are a team member. But if you are an admin, your privileges will be very broad.

The three methods to access the Jira REST API

Option 1: OAuth

OAuth is the standard for delegated authorization between apps. How often do you encounter a screen like this?

The application links used to integrate Jira with Confluence and Bitbucket follow OAuth, which is also Atlassian’s recommended access method to utilize the API.

Pros

This is the secure standard for accessing the API, as it doesn’t send user credentials over the browser.

Cons

To be honest, Atlassian is lagging behind a little bit in its implementation of OAuth 1.0, which many experts consider deprecated. Hopefully it will soon be possible to use OAuth 2.0. The fact that OAuth is an authorization protocol but is somehow being used in this context to authenticate a user gives an additional idea of the room for improvement.

When to use it

Whenever you’re using a third-party application that supports OAuth 

When can’t it be used

Older applications may not support OAuth. Additionally, when you’re building your own script or service, OAuth will be too too much effort.

See this tutorial on how to authenticate a Java application against Jira Server’s REST API using Oauth

Option 2: Cookie-based

In this method, the client authenticates against the Jira REST API, then utilizes Jira’s session cookie (JSessionID) in the subsequent request headers.

curl -X POST \ https://jira.example.com:8090/jira/rest/auth/1/session \ -H 'content-type: application/json' \ -d '{ "username": "myuser", "password": "mypassword" }'

The authentication step in cookie-based authentication

Pros

Since a session will not expire for some time, you can keep using the API without new authentication requests.

Cons

There are a few aspects here:

• Both the credentials, which are sent in JSON over HTTP,  and the cookie ID could be stolen, exposing access to your Jira.
• At some point the cookie will expire and your scripts will return an error.
• It’s no standard and it won’t be supported by virtually anything else. 
• Finally, cookie-based authentication won’t work in a Single Sign-On scenario because users don’t have the local password required to authenticate

When to use it

When you can’t handle OAuth or you need to write a quick script.

When can’t it be used

Whenever you need to access from a third-party application, the odds are their setup doesn’t support this method.

See this tutorial on how to authenticate a REST client against Jira Server’s REST API using cookies

Option 3: Basic Authentication

The basic authentication method consists of using the user’s credentials to authenticate against the API. It’s the simplest way but also the least secure, as it implies transmitting the credentials through HTTP and trusting that the client stores them securely in their database.

In this video you can see how simple it is to reverse-engineer the encoded credentials that are sent over an API call with basic auth.

Pros

Basic auth democratizes API utilization. Additionally, the security risks disappear when using personal access tokens (see section below).

Cons

The credentials stored in the browser can easily leak outside your organization during transmission or once they’re stored in an external database without proper encryption.

When to use it

Atlassian recommends using basic authentication “when experimenting with the REST API, writing a personal script, or for use by a bot”. Basic authentication is also often used in no-code automation platforms like Zapier, Unito, IFTTT or automate.io, where it can be replaced by the personal access tokens described in the next section.

When can’t it be used

When accessing from applications that require a higher security standard (typically OAuth).

Using Personal Access Tokens for Basic Authentication 

User credentials should be kept secret, period: any usage that makes them travel and be communicated to third parties is a severe risk. But let’s not throw the baby away with the bathwater just yet, because there is a way to maintain the ease of use and democratization factor of basic auth while keeping hackers at bay.

As mentioned above, personal access tokens should be employed to replace user credentials for authentication against Jira’s API. When used for out-of-the-box connectors or platforms like Zapier, this authentication method is sometimes called API Key Auth.

Advantages of Personal access tokens

• Security: if and when a token is compromised, it can simply be revoked without affecting the user’s sessions. Any other connections will use different tokens and will keep working as usual. 
• Compatibility with SSO: Regular basic auth doesn’t work with your company’s SSO, because there are no local passwords in Jira.
• Control: Atlassian offers no tools to monitor, gate and control the usage of the Jira API. Personal access tokens allow to implement permissions and scopes. Think of it this way: Jira lets every user access the API to play with the data they already have access to, but you should be able to define your own policies on top of that. For example, you could decide that only developers can access the API.

Getting personal access tokens for Atlassian applications

There are two options to start using personal access tokens in Atlassian products.

• Out-of-the-box: Personal access tokens are already included in Atlassian cloud applications and in Bitbucket server.

• Through Marketplace Apps: If you want to deploy API tokens for Jira or Confluence in Server or Data Center Hostings you will need to install resolution’s API Token Authentication for Jira.

You can also try the app for Confluence and for Bitbucket!

Conclusion

Let’s recap the basics. If the application you’re integrating with Jira Server supports OAuth, you should go ahead and use this method to access the API without any security trouble.

If you’re a developer building quick scripts for your own tasks and you’re used to using personal access tokens for your git operations, remember that you can securitize your API trail also in Jira and Confluence with API Token Authenticator.

If you are an administrator, implementing personal access tokens is a best practice when it comes to designing universal access policies for API usage that strike the right balance between business innovation and control.