Kantega SSO 5.7.0 REST API

This is a legacy documentation page for an older version of Kantega SSO. See the latest version of the REST API documentation here: https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/975241224

Starting with version 5.2 Kantega SSO Enterprise introduces REST API for managing plugin configuration. Our plugin exposes REST resources under the /ksso/api path.

The latest Kantega SSO REST API offers the following resources:

  1. General plugin information

  2. Snapshots of Config

  3. API Tokens


There is a neat plugin from Atlassian for discovery and testing of REST services that you can use for running requests on your Jira installation, you can get it here:
https://marketplace.atlassian.com/apps/1211542/atlassian-rest-api-browser?hosting=server&tab=overview
You can find our APIs by searching for ksso/api and uncheck the “show only public APIs” checkbox.

1. General plugin information

On the resource /rest/ksso/api/info/1.0/ping, you can perform GET requests to check the liveness of Kantega SSO Enterprise.

Example

GET
https://<atlassian-product-base-url>/rest/ksso/api/info/1.0/ping

Returns a HTTP 200 with a JSON document when Kantega SSO Enterprise is alive:

1 2 3 4 5 { "datetime": "2022-04-09T05:10:06.160+02:00[Europe/Oslo]", "response": "pong", "timestamp": 1649473806160 }

2. Snapshots of Config

The available services under /rest/ksso/api/snapshot are:

Resources under /rest for sysadmin

HTTP method

Description

Resources under /rest for sysadmin

HTTP method

Description

ksso/api/snapshot/1.0/config/snapshot/

GET

Returns a list of available snapshots

ksso/api/snapshot/1.0/config/snapshot/

POST

Saves a snapshot of the Kantega SSO configuration, with optional description

ksso/api/snapshot/1.0/config/snapshot/restore/{id}

POST

Restores snapshot with id

Examples

GET
https://<atlassian-product-base-url>/rest/ksso/api/snapshot/1.0/config/snapshot/
Returns a list of available snapshots like

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 [ { "applicationName": "JIRA", "applicationVersion": "8.16.1", "pluginVersion": "5.2.1-SNAPSHOT", "baseUrl": "https://elisor-p1:8443/jira", "timeMillis": 1641298623998, "description": "test", "filename": "sso-snapshot-2022-01-04-13_17_04.zip", "id": "sso-snapshot-2022-01-04-13_17_04", "readable": true }, { "applicationName": "JIRA", "applicationVersion": "8.16.1", "pluginVersion": "5.2.1-SNAPSHOT", "baseUrl": "https://elisor-p1:8443/jira", "timeMillis": 1641224273947, "description": "Backup before upgrade of config from version [unknown version] to 5.2.1-SNAPSHOT", "filename": "sso-snapshot-2022-01-03-16_37_53.zip", "id": "sso-snapshot-2022-01-03-16_37_53", "readable": true } ]

POST
/rest/ksso/api/snapshot/1.0/config/snapshot/
Without parameter will automatically generate a description like:
sso-snapshot-2021-12-02-19_51_50
You can also provide a description to tag the snapshot with more info:
/rest/ksso/api/snapshot/1.0/config/snapshot/?description=test-snapshot-2021-12-01

 

POST
/rest/ksso/api/snapshot/1.0/config/snapshot/restore/{id}
example:
/rest/ksso/api/snapshot/1.0/config/snapshot/restore/sso-snapshot-2021-12-02-19_51_50
Restores the snapshot with id sso-snapshot-2021-12-02-19_51_50. The description does not affect the id, so it’s best to retrieve the id of a snapshot with a specific description by running GET /rest/ksso/api/snapshot/1.0/config/snapshot/ and filtering the results with a specific description.

3. API Tokens

Resources under /rest/ksso/api/apitokens/2.0

Resources under /rest for sysadmin

HTTP method

Description

Resources under /rest for sysadmin

HTTP method

Description

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

DELETE

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

ksso/api/apitokens/2.0/admin/tokens

GET

Returns a list of all API tokens in the system.

Resources under /rest for user

ksso/api/apitokens/2.0/user/tokens

GET

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

ksso/api/apitokens/2.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>

1 2 3 4 5 { "tokenName":"Name" "description":"****", "validForDays":"180" }

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

DELETE

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

ksso/api/apitokens/2.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/2.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.

1 2 3 { "apiToken":"BBSVAkksjASLS****" }

 

 

Examples

GET

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

resulting in:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 {"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", "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", "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", "username": "john.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", "username": "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 [ { "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", "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", "username": "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.

 

POST

rest/ksso/api/apitokens/2.0/user/tokens

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

    1 2 3 4 5 { "tokenName": "Example name" "description":"Longer free-text optional description about the token's purpose", "validForDays":"180" }

    resulting in HTTP 201:

    1 2 3 4 5 6 7 8 9 { "validForDays": "180", "expiresAt": "2022-07-03T18:27", "apiToken": "YXPTJ2N52YYDDMKDHVYMQW2R7J7KMCJHQMDMUELXPKWDTR4QGRPKKS5BYTAPYAKBCMKKAMF2G3B6ATA2CVN3RWAFJX22MJEWC6QU2HTQIFJ4MVA4LOHS2ZKZ6OP3DKGR", "tokenName": "Example name" "description":"Longer free-text optional description about the token's purpose", "id": 67, "expiresAtMillis": 1656865644754 }
  2. With empty JSON body for default values
    {}

    resulting in HTTP 201:

    1 2 3 4 5 6 7 8 9 { "validForDays": "30", "expiresAt": "2022-02-03T17:29", "apiToken": "UEBDRPDHDWL4UKZS6DADIKTBU2WAULTDMR2NL2M2EPTKWMES2LHGISUBP7LRZUQ5N6VAT5LHJS3ZGEI7O2AASCC5BC52RC5YDP4QI76BU4GVEGKEAMKZQ73B234O3GF7", "tokenName": "api_token_2022-01-04T17:29:02.042", "description": "", "id": 68, "expiresAtMillis": 1643905742042 }
  3. With validForever for non-expiring token

    1 2 3 4 5 { "tokenName": "Example name" "description":"Longer free-text optional description about the token's purpose", "isValidForever":true }

    resulting in HTTP 201:

    1 2 3 4 5 6 7 8 { "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/2.0/user/expiry/status?id=65

results in:
HTTP 200

1 2 3 4 5 6 7 { "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.