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. 

This page explains how to create personal access tokens in Jira and Confluence.

For information on using personal access tokens in other Atlassian products, see:

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. 

On this page:

Creating PATs in application

  1. In your Atlassian application go to:
    • In Confluence, select your profile picture at 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 Personal Access Tokens .
  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.

You won’t be able to see your token again once you click Close .

Creating PATs using REST API

Send a POST HTTP request with the following body:

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

Though the expirationDuration parameter, you can define the number of days for which your token will remain valid.

to the following address:

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

In response, you'll receive the PAT. 

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://{confluenceBaseUrl}/rest/api/content

Revoking PATs

If for any reason, for instance, 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 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. 


Show me what system properties I can use to manage personal access tokens...
PropertyDefault valueDescription

atlassian.pats.enabled

true

Whether personal access tokens are globally enabled.

atlassian.pats.eternal.tokens.enabled

true

If users should be able to create tokens that do not expire.

atlassian.pats.mail.notifications.enabled

true

Whether mail notifications are globally enabled.

atlassian.pats.last.used.update.interval.mins

1

The interval at which the scheduler job is updating the 'last accessed at' property of each token, in minutes.

atlassian.pats.pruning.schedule.cron

0 0 0 * * ? - 12 am local time, every day

The CRON expression for the expired token pruning scheduler job.

atlassian.pats.pruning.delay.days

30

The delay before expired tokens are removed from the database, in days.

atlassian.pats.max.tokens.expiry.days

365

Maximum number of days for a token to expire. If you decided to change this property, the new value will apply only to tokens created after your change and won't affect already created tokens.

atlassian.pats.max.tokens.per.user

10

Maximum number of tokens allowed per user.

atlassian.pats.auth.cache.expiry.mins

60

The length of time, in minutes, an item can stay in the Authentication Cache before being removed.

atlassian.pats.auth.cache.max.items

5000

The maximum number of items allowed in the Authentication Cache.

atlassian.pats.expiry.check.schedule.cron

0 0 * * * ? - every hour

The CRON expression for the scheduler job that sends notifications about expired tokens and about tokens that will expire soon.

atlassian.pats.expiry.warning.days

5

How many days before sending an e-mail notification about tokens that will expire soon.

atlassian.pats.invalidate.session.enabled

true

If the session should be invalidated after succeeded authentication using personal access token.

atlassian.pats.token.name.length

40

The maximum number characters to be used for Token Name


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

Administer personal access tokens  

This feature is available with a Data Center license.

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  >  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


Last modified on Mar 1, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.