Kantega SSO 5.6.2 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. Snapshots of Config

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

2. API Tokens

Resources under /rest/ksso/api/apitokens/

Resources under /rest for sysadmin

HTTP method

Description

Resources under /rest for sysadmin

HTTP method

Description

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

DELETE

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

ksso/api/apitokens/1.0/admin/tokens

GET

Returns a list of all API tokens in the system.

Resources under /rest for user

ksso/api/apitokens/1.0/user/tokens

GET

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

ksso/api/apitokens/1.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 { "description":"****", "validForDays":"180" }

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

DELETE

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

ksso/api/apitokens/1.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/1.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/1.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 43 44 45 46 {"allApiTokens": [ { "createdAt": "2022-01-05T08:41:31", "createdAtMillis": 1641368491561, "description": "non-expiring", "id": 130, "expiresAt": "Never", "userKey": "admin", "username": "admin" }, { "timeUntilExpiryDays": "29", "createdAt": "2022-01-05T08:41:02", "createdAtMillis": 1641368462114, "timeUntilExpiryMillis": 2586019515, "description": "non-expiring", "id": 129, "expiresAt": "2022-02-04T08:41", "userKey": "admin", "username": "admin" }, { "timeUntilExpiryDays": "179", "createdAt": "2022-01-04T18:00:42", "createdAtMillis": 1641315642318, "timeUntilExpiryMillis": 15493199718, "description": "Google drive service", "id": 98, "expiresAt": "2022-07-03T19:00", "userKey": "JIRAUSER10100", "username": "john.doe" }, { "timeUntilExpiryDays": "29", "createdAt": "2022-01-04T18:00:20", "createdAtMillis": 1641315620320, "timeUntilExpiryMillis": 2533177720, "description": "User token 1", "id": 97, "expiresAt": "2022-02-03T18:00", "userKey": "JIRAUSER10100", "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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 [ { "timeUntilExpiryDays": "179", "createdAt": "2022-01-04T18:00:42", "createdAtMillis": 1641315642318, "timeUntilExpiryMillis": 15493838324, "description": "Google drive service", "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", "id": 97, "expiresAt": "2022-02-03T18:00", "userKey": "JIRAUSER10100", "username": "john.doe" } ]

 

POST

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

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

    1 2 3 4 { "description":"exampletoken", "validForDays":"180" }

    resulting in HTTP 201:

    1 2 3 4 5 6 7 8 { "validForDays": "180", "expiresAt": "2022-07-03T18:27", "apiToken": "YXPTJ2N52YYDDMKDHVYMQW2R7J7KMCJHQMDMUELXPKWDTR4QGRPKKS5BYTAPYAKBCMKKAMF2G3B6ATA2CVN3RWAFJX22MJEWC6QU2HTQIFJ4MVA4LOHS2ZKZ6OP3DKGR", "description": "exampletoken", "id": 67, "expiresAtMillis": 1656865644754 }
  2. With empty JSON body for default values
    {}

    resulting in HTTP 201:

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

    1 2 3 4 { "description":"exampletoken", "isValidForever":true }

    resulting in HTTP 201:

    1 2 3 4 5 6 7 { "apiToken": "64MVETBSHR7GFUXYCAPGPSERMOSKLLOQJHCVRXOYHWHGNUUZGUEDJFRARWCBPUZLXCNLZERXUCSB4D3H4TNSFTFY34C5IHEDILN7RXXNL6B2YVT4P7VBBE4RK7VMDZIO", "validForDays": "Forever", "description": "non-expiring", "id": 130, "expiresAt": "Never" }

 

GET

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

results in:
HTTP 200

1 2 3 4 5 6 7 { "expiresAt": "2022-07-03T15:22", "description": "example 1", "id": 65, "timeUntilExpiryMillis": 15541408230, "timeUntilExpiryDays": "179" }