Versions Compared

Old Version 3

changes.mady.by.user Elias Brattli Sørensen

Saved on

compared with

New Version 4

changes.mady.by.user Elias Brattli Sørensen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Resources under /rest for sysadmin

HTTP method

Description

ksso/api/apitokens/12.0/admin/delete/{id}

DELETE

Deletes the token with the given ID. Requires system administrator access.

ksso/api/apitokens/12.0/admin/tokens

GET

Returns a list of all API tokens in the system.

Resources under /rest for user

ksso/api/apitokens/12.0/user/tokens

GET

Returns a list of all API tokens for the logged in user

ksso/api/apitokens/12.0/user/tokens

POST

Accepts a JSON body with an entry like below, or an empty JSON body where default values are generated. The default is 30 day expiry and description api_token_<ISO formatted timestamp>

Code Block
languagejson
{
"tokenName":"Name"
"description":"****",
"validForDays":"180"
}

ksso/api/apitokens/12.0/user/delete/{id}

DELETE

Deletes the token with the given ID and returns plain text with a confirmation.

ksso/api/apitokens/12.0/user/expiry/status

GET

Accepts an API token ID in a query parameter as ?id Returns a JSON body with data about the expiry status for the given API token.

ksso/api/apitokens/12.0/user/refresh

PUT

Accepts a json body like below with the secret, or using the API token in the Authorization header if present and the JSON body is empty.

Code Block
languagejson
{
"apiToken":"BBSVAkksjASLS****"
}

Examples

GET

rest/ksso/api/apitokens/12.0/user/tokens as an admin user

...

Code Block
{"allApiTokens": [
    {
        "createdAt": "2022-01-05T08:41:31",
        "createdAtMillis": 1641368491561,
        "description": "non-expiring", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 130,
        "expiresAt": "Never",
        "userKey": "admin",
        "username": "admin"
    },
    {
        "timeUntilExpiryDays": "29",
        "createdAt": "2022-01-05T08:41:02",
        "createdAtMillis": 1641368462114,
        "timeUntilExpiryMillis": 2586019515,
        "description": "non-expiring", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 129,
        "expiresAt": "2022-02-04T08:41",
        "userKeyusername": "admin",
    },
    "username": "admin"
    },
    {
        "timeUntilExpiryDays": "179",
        "createdAt": "2022-01-04T18:00:42",
        "createdAtMillis": 1641315642318,
        "timeUntilExpiryMillis": 15493199718,
        "description": "Google drive service", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 98,
        "expiresAt": "2022-07-03T19:00",
        "userKeyusername": "JIRAUSER10100",
        "username": "johnjohn.doe"
    },
    {
        "timeUntilExpiryDays": "29",
        "createdAt": "2022-01-04T18:00:20",
        "createdAtMillis": 1641315620320,
        "timeUntilExpiryMillis": 2533177720,
        "description": "User token 1", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 97,
        "expiresAt": "2022-02-03T18:00",
        "userKeyusername": "JIRAUSER10100",
   john.doe"
    "username": "john.doe"
    },
    ...
]}

GET

rest/ksso/api/apitokens/1.0/user/tokens with authorization header logging in user Authorization Basic john.doe:<password/api token>

Logged in user john.doe gives all the tokens belonging to john.doe:

...

Due to a bug in the new 2.0 API Token REST service, the tokenName field is actually returned as description on GET (which was the format on version 1.0), while the true reflection of the data is present in the return on POST and in the GUI. The intention is however that the tokenName field now will reflect the attribute in the GUI, while description now is an added optional free-text field. This will be fixed in a patch version soon. See the token list in the GUI for a truly reflected version of the token list.

GET

rest/ksso/api/apitokens/2.0/user/tokens with authorization header logging in user Authorization Basic john.doe:<password/api token>

Logged in user john.doe gives all the tokens belonging to john.doe:

Code Block
[
    {
        "timeUntilExpiryDays": "179",
        "createdAt": "2022-01-04T18:00:42",
        "createdAtMillis": 1641315642318,
        "timeUntilExpiryMillis": 15493838324,
        "description": "Google drive service", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 98,
        "expiresAt": "2022-07-03T19:00",
        "userKey": "JIRAUSER10100",
        "username": "john.doe"
    },
    {
        "timeUntilExpiryDays": "29",
        "createdAt": "2022-01-04T18:00:20",
        "createdAtMillis": 1641315620320,
        "timeUntilExpiryMillis": 2533816318,
        "description": "User token 1", // Due to a bug in 5.7.0, this field is actually the token name
        "id": 97,
        "expiresAt": "2022-02-03T18:00",
        "userKey": "JIRAUSER10100",
        "username": "john.doe"
    }
]

POST

rest/ksso/api/apitokens/1.0/user/tokens

With request body to create token with custom description and duration

Code Block
languagejson
{
"description":"exampletoken",
"validForDays":"180"
}

...

Due to a bug in the new 2.0 API Token REST service, the tokenName field is actually returned as description on GET (which was the format on version 1.0), while the true reflection of the data is present in the return on POST and in the GUI. The intention is however that the tokenName field now will reflect the attribute in the GUI, while description now is an added optional free-text field. This will be fixed in a patch version soon. See the token list in the GUI for a truly reflected version of the token list.

POST

rest/ksso/api/apitokens/1.0/user/tokens

  1. With request body to create token with custom description and duration

    Code Block
    languagejson
    {
  "validForDaystokenName": "180",
 Example name"
"expiresAtdescription":"Longer "2022-07-03T18:27",
  "apiToken": "YXPTJ2N52YYDDMKDHVYMQW2R7J7KMCJHQMDMUELXPKWDTR4QGRPKKS5BYTAPYAKBCMKKAMF2G3B6ATA2CVN3RWAFJX22MJEWC6QU2HTQIFJ4MVA4LOHS2ZKZ6OP3DKGR",
  "description": "exampletoken",
  "id": 67,
  "expiresAtMillis": 1656865644754
}

    With empty JSON body for default values
    {}

    resulting in HTTP 
    free-text optional description about the token's purpose",
"validForDays":"180"
}

    resulting in HTTP 201:

    Code Block
    languagejson
    {
  "validForDays": "30180",
  "expiresAt": "2022-0207-03T1703T18:2927",
  "apiToken": "UEBDRPDHDWL4UKZS6DADIKTBU2WAULTDMR2NL2M2EPTKWMES2LHGISUBP7LRZUQ5N6VAT5LHJS3ZGEI7O2AASCC5BC52RC5YDP4QI76BU4GVEGKEAMKZQ73B234O3GF7YXPTJ2N52YYDDMKDHVYMQW2R7J7KMCJHQMDMUELXPKWDTR4QGRPKKS5BYTAPYAKBCMKKAMF2G3B6ATA2CVN3RWAFJX22MJEWC6QU2HTQIFJ4MVA4LOHS2ZKZ6OP3DKGR",
  "descriptiontokenName": "api_token_2022-01-04T17:29:02.042Example name"
  "description":"Longer free-text optional description about the token's purpose",
  "id": 6867,
  "expiresAtMillis": 16439057420421656865644754
}

  2. With validForever for non-expiring token

    Code Block
    {
"description":"exampletoken",
"isValidForever":true
}

    resulting in HTTP 201:

    Code Block{

    empty JSON body for default values
    {}

    resulting in HTTP 201:

    Code Block
    languagejson
    {
  "validForDays": "30",
  "expiresAt": "2022-02-03T17:29",
  "apiToken": "64MVETBSHR7GFUXYCAPGPSERMOSKLLOQJHCVRXOYHWHGNUUZGUEDJFRARWCBPUZLXCNLZERXUCSB4D3H4TNSFTFY34C5IHEDILN7RXXNL6B2YVT4P7VBBE4RK7VMDZIOUEBDRPDHDWL4UKZS6DADIKTBU2WAULTDMR2NL2M2EPTKWMES2LHGISUBP7LRZUQ5N6VAT5LHJS3ZGEI7O2AASCC5BC52RC5YDP4QI76BU4GVEGKEAMKZQ73B234O3GF7",
  "validForDaystokenName": "Foreverapi_token_2022-01-04T17:29:02.042",
  "description": "non-expiring",
  "id": 13068,
  "expiresAtexpiresAtMillis": "Never"
}

GET

/rest/ksso/api/apitokens/1.0/user/expiry/status?id=65

results in:
HTTP 200

...

languagejson

...

  1. 1643905742042
}

  2. With validForever for non-expiring token

    Code Block
    {
"tokenName": "Example name"
"description":"Longer free-text optional description about the token's purpose",
"isValidForever":true
}

    resulting in HTTP 201:

    Code Block
    {
  "apiToken": "64MVETBSHR7GFUXYCAPGPSERMOSKLLOQJHCVRXOYHWHGNUUZGUEDJFRARWCBPUZLXCNLZERXUCSB4D3H4TNSFTFY34C5IHEDILN7RXXNL6B2YVT4P7VBBE4RK7VMDZIO",
  "validForDays": "Forever",
  "tokenName": "Example name"
  "description":"Longer free-text optional description about the token's purpose",
  "id": 130,
  "expiresAt": "Never"
}

GET

/rest/ksso/api/apitokens/1.0/user/expiry/status?id=65

results in:
HTTP 200

Code Block
languagejson
{
  "expiresAt": "2022-07-03T15:22",
  "apiTokenDescription": "Token name", // Due to a bug in 5.7.0, this field is actually the token name
  "id": 65,
  "timeUntilExpiryMillis": 15541408230,
  "timeUntilExpiryDays": "179"
}

Due to a bug in the new 2.0 API Token REST service, the tokenName field is actually returned as apiTokenDescription on expiry status GET (which was the format on version 1.0), while the true reflection of the data is present in the return on POST and in the GUI. The intention is however that the tokenName field now will reflect the attribute in the GUI, while description now is an added optional free-text field. This will be fixed in patch version 5.7.1 soon. See the token list in the GUI for a truly reflected version of the token list.