Using Personal Access Tokens

Personal access tokens (PATs) are a secure way to use scripts and integrate external applications with your Atlassian application. If an external system is compromised, you simply revoke the token instead of changing the password and consequently changing it in all scripts and integrations.

Personal access tokens are a safe alternative to using username and password for authentication with various services. 

Before you begin

You can create and use personal access tokens in Data Center and server editions of the following Atlassian applications: 

• Jira Core 8.14 and later
• Jira Software 8.14 and later
• Jira Service Management 4.15 and later
• Confluence 7.9 and later 

The admin view of personal access tokens is available in the Data Center version of these applications. 

Creating PATs in the application

All users are allowed to create their own PATs, which will match their current permission level. To create the tokens, you may follow these steps:

1. In your Atlassian application go to:
   
   • In Confluence, select your profile picture at the top right of the screen, then choose  Settings > Personal Access Tokens.
   • In Jira, select your profile picture at the top right of the screen, then choose Profile. Once you access your profile, select Personal Access Tokens in the left-hand menu.
2. Select Create token.
3. Give your new token a name.

4. Optionally, for security reasons, you can set your token to automatically expire after a set number of days. 

   The EXPIRES SOON status appears 5 days before the actual expiration date. Once the token expires, you can't reactivate it. You must create a new token.

5. Click Create.

Your personal access token is created. Copy the token and store it in a safe space.

Creating PATs using REST API

To create the PAT using REST API, you can send a POST HTTP request as exemplified below, and in response, you'll receive the PAT. Please note that you cannot create PATs on behalf of someone else.
Be sure to replace the '{{baseUrlOfYourInstance}}' with the actual URL for your Jira/Confluence instance.

{{baseUrlOfYourInstance}}/rest/pat/latest/tokens

{
    "name": "tokenName",
    "expirationDuration": 90
}

In order to create the PAT through the REST endpoint you'll need to make sure to authenticate yourself on the request, so that Jira can verify if you are eligible to create a PAT, and also to which user associate it to.

• Example of how the request can be made with authentication using curl:

curl -X POST {{baseUrlOfYourInstance}}/rest/pat/latest/tokens -H "Content-Type: application/json" -d '{"name": "tokenName","expirationDuration": 90}' --user "username:password"

curl -X POST {{baseUrlOfYourInstance}}/rest/pat/latest/tokens -H "Authorization: Bearer <Token>" -H "Content-Type: application/json" -d '{"name": "tokenName","expirationDuration": 90}'

Using PATs

To use a personal access token for authentication, you have to pass it as a bearer token in the Authorization header of a REST API call.

Here's an example using cURL to call the REST API with a bearer token: 

curl -H "Authorization: Bearer <yourToken>" https://{baseUrlOfYourInstance}/rest/api/content

A couple of important notes:

• The '{{baseUrlOfYourInstance}}' tag is an example, and should be replaced with the actual URL for your Jira/Confluence instance.
  
• The '/rest/api/content' endpoint is not a valid one, and should also only be considered as an example. A listing of the REST API endpoints for Jira & Confluence can be found on the Jira Server platform REST API reference and Confluence Server platform REST API reference pages respectively.
• For the PAT authentication, you should only replace '<yourToken>' with the actual PAT. The "Bearer" part should not be changed, nor should you need to inform which user is making the request.
• If attempting to use the PAT on a script or with some other method, you should still follow the Bearer Token OAuth standard.

Revoking PATs

If for any reason, for instance, a security breach, you need to revoke your token, you can do it quickly from your Atlassian application: 

1. In your Atlassian application go to:
   
   • In Jira select your profile picture at the top right of the screen, then choose  Personal Access Tokens.
   • In Confluence, select your profile picture at the top right of the screen, then choose Settings > Personal access tokens.
2. Select Revoke next to the token you want to delete.
3. Confirm your choice. 

Your token is now revoked and can't be used for further authentication. 

Limit token creation

Administrators can use system properties to limit the number of tokens people can create, and set expiry rules. 

 To find out how to apply system properties in your application:

• For Jira, see Setting properties and options on startup
• For Confluence, see  Configuring System Properties

Administer personal access tokens  

In Data Center applications, administrators can see a list of all tokens created in the site, and revoke any of these tokens.

To administer personal access tokens:

1. In your Atlassian application go to:
   • In Jira, select   > System > Administering personal access tokens.
   • In Confluence, select  >  Users & Security > Administering personal access tokens .

In this view, you can filter your tokens by the author, creation and expiration date, and the last time the token was used for authentication. Admins can revoke individual tokens and delete multiple tokens at once. To bulk revoke, select tokens you want to revoke, and click Bulk revoke.