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: Kantega SSO Enterprise REST API

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:

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:
Atlassian REST API Browser | Atlassian Marketplace
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:

{
    "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

[
  {
    "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> `{ "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.

Examples

GET

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

resulting in:

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:

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

With request body to create token with custom description and duration
resulting in HTTP 201:
With empty JSON body for default values
{}
resulting in HTTP 201:
With validForever for non-expiring token
resulting in HTTP 201:

GET

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

results in:
HTTP 200

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.