User Token Management for Server and Data Center

Users can manage their tokens by clicking on the profile icon and selecting the API Token Authentication Link

Jira Server or Data Center

Confluence Server or Data Center

Creating a new token

Creating a new token with the corresponding button in the "My API Tokens" tab

• Enter a description for the token
• Select the expiration time within the boundaries defined by your administrator
• Choose whether the token should have Read Only or Read & Write scope *
  * Read more about scopes in the infobox at the end of this section

If your administrator has not enabled the Users may only create "Read Only tokens" setting,
you will see additional info stating that the token will only have a read-only scope,
so that you may only use it for REST requests of type GET:

Click on the Create API Token button to retrieve your token along with a summary of preferences:

You may now access the REST API via Basic Authorization, using your username and the token, instead of your user password (if you have any).
Please be aware of possible token scope restrictions as defined by your administrator (see the next paragraph for details).

Token Scopes

There are currently two token scopes available.

Read Only

Only the GET, HEAD and OPTIONS HTTP request types are allowed, using a token on endpoints requiring any other type will result in a 403 Forbidden error.
There are two exceptions/ endpoints not affected by that:

• the Jira Session endpoint to which you can POST your username and token to retrieve a session cookie
• the API Token Authentication endpoint to which a user can POST details to create a token if permitted to

Read & Write

All HTTP request types are allowed to be used.
Every type other than GET, HEAD and OPTIONS suggests that it is a write operation somehow, manipulating existing data in some form.

Rate Limiting

If your administrator has enabled rate-limiting for requests that were authenticated with an API token it will be automatically applied to your token.

Like in the picture below you'll see

• for how long the rate limit is valid until it gets reset again
• how many requests you can make within that period

Example: 

• at some point, you make your first request with the token
• from that moment on you are allowed to make 5 requests for the next 5 minutes
• details about the current rate limit status for your token are contained in the response headers:
  

• if you exceed the amount in ATA-RL-REMAINING, you'll receive error 429 (Too many requests) and some more information as JSON in the response itself

  {
      "remainingMillisecondsUntilRateLimitReset": 283893,
      "requestBucketSize": 5,
      "currentRequestBucketSize": 0,
      "rateLimitMessage": "You've exceeded the rate limit for your token"
  }

  XML
• the field remainingMillisecondsUntilRateLimitReset provides the amount of time in milliseconds until the request-bucket is filled again and you can execute more requests 

A rate limit is always assigned to an individual API token and can't be changed once that has been created.

Should your administrator have raised the limit in the meantime, you need to create a new token or request one from a person who creates it for you (in case you don't have permission to do that yourself).

Revoking tokens

To revoke any token, simply use the Delete operation in the Actions column.

A confirmation modal window will ask for confirmation again, displaying all the token details for your convenience. 

Token Manager

Creating a token for other users

If your administrator has granted permissions to create tokens for other users, you'll see another tab called "Token Manager".
It also allows you to filter tokens of all users and create tokens for any of them

To create a token for somebody else, press the New API Token button again and select a user to create a token for.
Provide a description and select an expiration time. The minimum value here is what your administrator has defined.
You might choose a lower value, but you can't select anything above, if applicable at all.

You may also provide a token scope (Read Only or Read & Write) as described earlier.
Not selecting any scope will create a Read & Write token

Rate Limiting

If the administrator has enabled rate-limiting for requests with API tokens it will also be applied to tokens created for another user.
You can not select or enter values greater than these but you could use smaller values. 

For the example in the picture below it could be any lifetime smaller than 4 hours and a smaller amount of requests in the bucket.

Revoking tokens of other users

If you have permission to access the Token Manage tab, you can revoke/ delete tokens in the same way you would your own tokens.
Just use the delete icon/ link in the Action column.

Filter Tokens

The token manager tab also provides filter capabilities.

Select one or more users for whom you want to see their tokens, enter a string from the token description to search for (search is case insensitive)
or filter for created-, last used- or expiration date. 

The date filters provide presets to choose from but you can also define a custom range for each