Search
  • Julie Gums

What is the value of our API Token Authentication app?

Updated: Aug 6



Question

What is the value of our API Token Authentication app?


What are the scenarios for API Token Authentication?

There are multiple scenarios where the API Token Authentication app provides benefits.

  1. One of the first ones is in Single Sign-On environments, where users often don't have local passwords or usernames anymore. They can't use basic auth on the API anymore. That's a very common mechanism that third-party integrations like Zapier, Microsoft Flow, used to use the Jira or Confluence API. In SSO environments very often users can't use these API connections.

  2. The other value is that API tokens are generally considered more secure than using basic auth with essentially your normal enterprise password. They are are complex long strings and can have an expiry date. You can have a different one per app/script and revoke them, if the token got lost. But there's also a lot more admin control that you can do on the API. And with our plugin, you can for example disable the username and password basic auth completely, you can also define groups that can create, manage tokens that can use tokens, et cetera.

Admin Setup

Installing The API Token Authentication App

Before you begin you must have the system administrators global permissions before you can carry out the instructions on this page

Tip In Jira use Keyboard Shortcuts to access menu items: type the g key on the keyboard twice quickly, a window will pop out and you can search for any configuration item
  1. Log in as a user with the system administrators permission

  2. Click at the cog icon at top right of the screen in Jira or Confluence to access the Manage app or Manage add-ons section

  3. Click Find new add-ons from the left-hand side of the page and enter resolution API Token into the Search the marketplace field.
 The appropriate version appears in the search results.

  4. Click Try free to begin a new trial or Buy now to purchase a license for API Token Authentication.
 You're prompted to log into My.Atlassian. The app begins to download.

  5. Enter your information and click Generate license when redirected to MyAtlassian.

  6. Click Apply license.
 (If you're using an older version of UPM, you can copy and paste the license into your Jira or Confluence instance.)

Read here more about how to upgrade and disable API Token as Admin and go here for the App configuration.


User Guide

User Token Management

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


Creating A New Token

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

  1. Enter a description for the token

  2. Select the expiration time within the boundaries defined by your administrator

  3. Choose whether the token should have Read Only or Read & Write scope

If your administrator has not enabled the Users may only create "Read Only tokens"setting,

you will see an additional info stating that the token will only have 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.


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


Revoking Tokens Of Other Users

If you have permissions 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.

platinum_low-res.png

Newsletter      Support      Marketplace      Documentation      Imprint      Privacy Policy