API Token AuthenticationAPI Token Authentication
Try For Free

REST API

The API Token Authentication app currently provides a few REST API endpoints.
Please find below a summary of what can be done already.

Create a new token 

Create a new token by providing its description as follows. The response will contain the token automatically generated.

  1. curl -v -u user:password -d '{"tokenDescription":"<enter-your-token-description-here>"}' POST https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

You could also provide an expiration period in months, provided that it is smaller or equal to the one defined by the administrator in the system-wide settings. 
In the below example, a token with an expiration time of just one month is created:

  1. curl -v -u user:password -d '{"tokenDescription":"<enter-your-token-description-here>", "tokenValidityTimeInMonths" : 1}' POST https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

Since version 1.5.0 you may also pass an ISO 8601 date-time string for the tokenExpirationDateTime field in the payload.

  1. curl -v -u user:password -d '{"tokenDescription":"Custom expiration", "tokenExpirationDateTime" : "2020-10-19T10:29:00.000+02:00"}' POST https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

Please note that it must be below or equal to the maximum allowed value set by your administrator. If not, you'll get a 400 error with some details:

  1. {
  2. "errorMessage" : "The custom expiration you've provided is greater than the maximum defined by your administrator. You need to provide a date within the next 12 months."
  3. }

Otherwise, it will return the token response. Please note that tokenValidityTimeInMonths is not important then, but tokenExpirationDateTime and tokenExpirationDateTimeMillis instead.

  1. {
  2. "plainTextToken": "pltFERJm3XCjoRnG48wmIiEE3lJWCUD01tjdtv",
  3. "tokenDescription": "Custom expiration",
  4. "tokenForUserKey": "JIRAUSER10100",
  5. "tokenValidityTimeInMonths": 12,
  6. "tokenExpirationDateTime": "2020-10-19T10:29:00.000+02:00",
  7. "tokenExpirationDateTimeMillis": 1603096140000,
  8. "tokenScope": 0
  9. }


You need to include the offset to UTC in that string so that the expiration time works as expected in the users time zone.
You could validate the expiration date time by reviewing it again in your token list:
image2020-9-22_17-35-42.png


Update a token description

  1. curl -v -u user:password -d '{"tokenDescription":"Updated token description"}' -X PATCH https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/<token-id> --header "Content-Type: application/json"

List all tokens

To get an overview of what tokens you've added for your user and to grab an id of one to update or delete it, execute the request below.
You may omit the pipe symbol and python command at the end, it is just for beautifying the JSON response.

  1. curl -v -u user:password GET https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/ | python -mjson.tool

which produces output like:

  1. [
  2. {
  3. "created": 1573814077364,
  4. "description": "Automation token",
  5. "id": 4,
  6. "lastAccessed": 1573814464012
  7. }
  8. ]

List all tokens (all users)

The REST endpoint to retrieve token details for all users is only accessible for users with the Create Token On Behalf Permission. Please read more about permissions here.
You can also use the filter parameters described here to filter for specific properties. 

To get an overview of all tokens in the system (including the expired ones) and to grab an id of one to update or delete it, execute the request below. You may omit the pipe symbol and python command at the end, it is just for beautifying the JSON response.

  1. curl -v -u admin:password GET https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/tokensByFilter | python -mjson.tool

which produces output like:

  1. [
  2. {
  3. "created": 1629212615280,
  4. "description": "API Token from 2021-08-17",
  5. "id": 1,
  6. "lastAccessed": 0,
  7. "tokenCreatedByUserKey": "admin",
  8. "tokenForUserKey": "admin",
  9. "tokenScope": 2,
  10. "validUntil": 1631891015279
  11. },
  12. {
  13. "created": 1629212647398,
  14. "description": "API Token from 2021-08-17",
  15. "id": 2,
  16. "lastAccessed": 0,
  17. "tokenCreatedByUserKey": "admin",
  18. "tokenForUserKey": "JIRAUSER10329",
  19. "tokenScope": 2,
  20. "validUntil": 1634483047398
  21. }
  22. ]

Delete a token 

Grab a token ID retrieved with the previous call and put it to end of the call: 

  1. curl -v -u user:password -X DELETE https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/<token-id>

Administrative REST API Methods

Since version 1.1.0, sys admins may use the endpoints below as well

Create Tokens for other Users

Admins may create token for other users by providing their user key in the request payload. If no no token validity time is provided, the system default will be automatically assigned. 
How to get a key for a user in Jira/ Confluence is explained in the previous chapter.

  1. curl -v -u admin:passwordOrToken -d '{"tokenDescription":"token for another user", "tokenForUserKey":"JIRAUSER10105"}' POST https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

If a  token validity time is provided, then it will be validated and adjusted to the value set in the system wide settings, if required. This prevents again trying to keep a token valid forever or i.e. 12 month, where only 6 are allowed.

  1. curl -v -u admin:passwordOrToken -d '{"tokenDescription":"token for another user", "tokenForUserKey":"JIRAUSER10105","tokenValidityTimeInMonths":12}' POST https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

Delete all tokens for a user 

This call will work for sysadmins only and otherwise throw 403. Please note that the user key is passed, which is different than the name *.  

  1. curl -v -u admin:password -X DELETE https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/deleteAllFor/<user-key-not-user-name>

Get User Key for a User

* you can get a user's key by  using the REST API as an admin
The result will contain a key or userKey field (Jira or Confluence)

Jira

  1. curl -u admin:password GET https://<your-jira>/rest/api/2/user?username=some.username | python -mjson.tool
  4. {
  5. "active": true,
  6. "applicationRoles": {
  7. "items": [],
  8. "size": 1
  9. },
  10. "avatarUrls": {
  11. "16x16": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=16",
  12. "24x24": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=24",
  13. "32x32": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=32",
  14. "48x48": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=48"
  15. },
  16. "displayName": "Some User",
  17. "emailAddress": "some@user.com",
  18. "expand": "groups,applicationRoles",
  19. "groups": {
  20. "items": [],
  21. "size": 1
  22. },
  23. "key": "JIRAUSER10100",
  24. "locale": "en_US",
  25. "name": "Some User",
  26. "self": "https://<your-jira>/rest/api/2/user?username=some.username",
  27. "timeZone": "GMT"
  28. }

Confluence

  1. curl -v -u admin:password GET https://<your-confluence>/rest/api/user?username=some.username | python -mjson.tool
  3. {
  4. "_expandable": {
  5. "status": ""
  6. },
  7. "_links": {
  8. "base": "https://<your-confluence>",
  9. "context": "",
  10. "self": "https://<your-confluence>/rest/api/user?key=e4fc80a46ebbdf4c016fa42e69be01f8"
  11. },
  12. "displayName": "some.username",
  13. "profilePicture": {
  14. "height": 48,
  15. "isDefault": true,
  16. "path": "/images/icons/profilepics/default.svg",
  17. "width": 48
  18. },
  19. "type": "known",
  20. "userKey": "e4fc80a46ebbdf4c016fa42e69be01f8",
  21. "username": "some.username"
  22. }

Get User Key by E-Mail

Since version 1.5.0 users with the Create Token On Behalf Permission can use a REST endpoint which allows them to retrieve a user key by providing an e-mail address of a user.
If this address is valid and a unique (only assigned to a single user), the endpoint will return the user key.

  1. curl -u user-with-create-token-on-behalf-permission "https://jobo-jira-sd.klab.resolution.de/rest/de.resolution.apitokenauth/latest/user/userKeyByEmail?email=john.doe@deville.com"
  2. JIRAUSER12800

Response if not a single user has the email address

  1. {
  2. "errorMessage" : "Could not retrieve a userkey for email 'unknown@deville.com', error was: NOT_FOUND"
  3. }

Response if the email address has been assigned to more than one user:

  1. {
  2. "errorMessage": "Can't return a userkey since there is more than one user with the email 'john.doe@deville.com'"
  3. }

Filter User Tokens

Since version 1.3.0, the Token Manager tab (read the Token Manager section here) provides an easy-to-use interface for almost all purposes.
There is also a REST endpoint to filter for tokens, i.e. to remind users about their tokens soon to expire, with a custom integration.
We are planning to integrate notifications for tokens to expire soon in a future release.

Filter parameters

Parameter

Value

Comment

userFilter

valid user key

read above how to get a user key for a name or by email address;
if you want to filter for more than one user, repeat that parameter for as many users you want to filter for

descriptionFilter

search term

string to search for in all token descriptions

notValidAfter

epoch unix timestamp

tokens not valid anymore after that date/ time in milliseconds

tokenScope

integer

0 = no scope (all pre 1.5.0 tokens), 1 = read only, 2 = read/ write

fromCreated

epoch unix timestamp


untilCreated

epoch unix timestamp


fromLastUsed

epoch unix timestamp


untilLastUsed

epoch unix timestamp


fromExpiresDuring

epoch unix timestamp


untilExpiresDuring

epoch unix timestamp



Below an example of all above parameters but the notValidAfter parameter

  1. curl -u admin:passwordOrToken "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?userFilter=JIRAUSER00007&userFilter=JIRAUSER13517&fromCreated=1601503200000&untilCreated=1604185199999&descriptionFilter=findme&tokenScope=1&fromLastUsed=1601503200000&untilLastUsed=1604185199999&fromExpiresDuring=1604185200000&untilExpiresDuring=1612133999999" | python -mjson.tool


Below examples shows how to receive all tokens not valid anymore after a certain date/ time in milliseconds

Instead of passing a timestamp as parameter value for notValidAfter, you can also send -1 which will return all tokens


  1. curl -u admin:passwordOrToken "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?notValidAfter=1688918956972" | python -mjson.tool

And returns

  1. {
  2. "content": [
  3. {
  4. "created": 1580832062985,
  5. "description": "Shell Script",
  6. "id": 64,
  7. "lastAccessed": 0,
  8. "tokenCreatedByUserKey": "admin",
  9. "tokenForUserKey": "admin",
  10. "validUntil": 1596556862985
  11. },
  12. {
  13. "created": 1580832051168,
  14. "description": "Automation Script",
  15. "id": 63,
  16. "lastAccessed": 0,
  17. "tokenCreatedByUserKey": "admin",
  18. "tokenForUserKey": "admin",
  19. "validUntil": 1612454451168
  20. },
  21. {
  22. "created": 1580892710444,
  23. "description": "API Token from 2020-02-05",
  24. "id": 65,
  25. "lastAccessed": 1580892730216,
  26. "tokenCreatedByUserKey": "admin",
  27. "tokenForUserKey": "admin",
  28. "validUntil": 1612515110443
  29. },
  30. {
  31. "created": 1580893252170,
  32. "description": "token for another user",
  33. "id": 66,
  34. "lastAccessed": 0,
  35. "tokenCreatedByUserKey": "admin",
  36. "tokenForUserKey": "JIRAUSER10105",
  37. "validUntil": 1612515652170
  38. }
  39. ],
  40. "currentPage": 0,
  41. "limit": 50,
  42. "offset": 0,
  43. "paginationLinks": {
  44. "baseUrl": "https://your-jira-or-confluence",
  45. "nextPage": "",
  46. "previousPage": ""
  47. },
  48. "total": 4,
  49. "totalPages": 1
  50. }

The results are paged and you may only retrieve 50 results max per page. Below another example with paging:

  1. curl -u admin:passwordOrToken "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?page=0&limit=1&notValidAfter=1688918956972"


Don't forget to wrap the URL in double quotes, when doing that on the command line, as the & would be interpreted as sending the process into the background

The output would look like the below and contain links to the previous and next page, if available.

  1. {
  2. "content": [
  3. {
  4. "created": 1580832062985,
  5. "description": "Shell Script",
  6. "id": 64,
  7. "lastAccessed": 0,
  8. "tokenCreatedByUserKey": "admin",
  9. "tokenForUserKey": "admin",
  10. "validUntil": 1596556862985
  11. }
  12. ],
  13. "currentPage": 0,
  14. "limit": 1,
  15. "offset": 0,
  16. "paginationLinks": {
  17. "baseUrl": "https://your-jira-or-confluence",
  18. "nextPage": "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?page=1&limit=1&notValidAfter=1688918956972",
  19. "previousPage": ""
  20. },
  21. "total": 4,
  22. "totalPages": 4
  23. }

REST API Error Response Codes

REST Endpoint

Action

HTTP Result Code

Regular REST endpoints
with the API Token app enabled and Basic Auth with password still allowed

User accesses the endpoint with a token expired or wrong

401

Regular REST endpoints
with the API Token app enabled and Basic Auth with password disabled

User accesses the endpoint with a token expired or wrong

401

Regular REST endpoints
with the API Token app enabled and Basic Auth with password enabled

User accesses the endpoint with a regular password

401

API Token REST endpoints (listed in the guide above)

Non sys-admin user is trying to access an API Token app endpoint only intend for sysadmins

403

Please be aware that depending on the system settings, Jira & Confluence might increase the failed login counter up to a point where the user would need to enter a captcha to reset that
counter or let a sys admin do that for him/ her. Until then, every further attempt to access the REST API will result in a 403 Forbidden error.

Read more about the security configuration below:
Jira: https://your-jira/secure/admin/ViewApplicationProperties.jspa - Maximum Authentication Attempts Allowed
Confluence: Atlassian documentation https://confluence.atlassian.com/doc/configuring-captcha-for-failed-logins-216957808.html