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:
https://marketplace.atlassian.com/apps/1211542/atlassian-rest-api-browser?hosting=server&tab=overview
You can find the Kantega SSO REST API 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
GEThttps://<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 (Now Backup & restore in GUI)
The available services under /rest/ksso/api/snapshot are:
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
GEThttps://<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/3.0
Resources under /rest for sysadmin | HTTP method | Description |
---|---|---|
ksso/api/apitokens/3.0/admin/delete/{id} | DELETE | Deletes the token with the given ID. Requires system administrator access. |
ksso/api/apitokens/3.0/admin/tokens | GET | Returns a list of all API tokens in the system. |
Resources under /rest for user | ||
ksso/api/apitokens/3.0/user/tokens | GET | Returns a list of all API tokens for the logged in user |
ksso/api/apitokens/3.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/3.0/user/delete/{id} | DELETE | Deletes the token with the given ID and returns plain text with a confirmation. |
ksso/api/apitokens/3.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/3.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. {
"apiToken":"BBSVAkksjASLS****"
}
|
Examples
GET
rest/ksso/api/apitokens/3.0/user/tokens
as an admin user
resulting in:
{"allApiTokens": [
{
"createdAt": "2022-01-05T08:41:31",
"createdAtMillis": 1641368491561,
"tokenName": "non-expiring",
"description": "Longer free-text optional description about the token's purpose",
"id": 130,
"expiresAt": "Never",
"username": "admin"
},
{
"timeUntilExpiryDays": "29",
"createdAt": "2022-01-05T08:41:02",
"createdAtMillis": 1641368462114,
"timeUntilExpiryMillis": 2586019515,
"tokenName": "non-expiring2",
"description": "Longer free-text optional description about the token's purpose",
"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,
"tokenName": "User token 1",
"description": "Longer free-text optional description about the token's purpose",
"id": 97,
"expiresAt": "2022-02-03T18:00",
"username": "john.doe"
},
...
]}
GET
rest/ksso/api/apitokens/3.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:
[
{
"timeUntilExpiryDays": "179",
"createdAt": "2022-01-04T18:00:42",
"createdAtMillis": 1641315642318,
"timeUntilExpiryMillis": 15493838324,
"tokenName": "Google drive service",
"description": "Longer free-text optional description about the token's purpose",
"id": 98,
"expiresAt": "2022-07-03T19:00",
"username": "john.doe"
},
{
"timeUntilExpiryDays": "29",
"createdAt": "2022-01-04T18:00:20",
"createdAtMillis": 1641315620320,
"timeUntilExpiryMillis": 2533816318,
"tokenName": "User token 1",
"description": "Longer free-text optional description about the token's purpose",
"id": 97,
"expiresAt": "2022-02-03T18:00",
"username": "john.doe"
}
]
POST
rest/ksso/api/apitokens/3.0/user/tokens
With request body to create token with custom description and duration
{ "tokenName": "Example name", "description":"Longer free-text optional description about the token's purpose", "validForDays":"180" }
resulting in HTTP 201:
{ "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 }
With empty JSON body for default values
{}resulting in HTTP 201:
{ "validForDays": "30", "expiresAt": "2022-02-03T17:29", "apiToken": "UEBDRPDHDWL4UKZS6DADIKTBU2WAULTDMR2NL2M2EPTKWMES2LHGISUBP7LRZUQ5N6VAT5LHJS3ZGEI7O2AASCC5BC52RC5YDP4QI76BU4GVEGKEAMKZQ73B234O3GF7", "tokenName": "api_token_2022-01-04T17:29:02.042", "description": "", "id": 68, "expiresAtMillis": 1643905742042 }
With validForever for non-expiring token
{ "tokenName": "Example name", "description":"Longer free-text optional description about the token's purpose", "isValidForever":true }
resulting in HTTP 201:
{ "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/3.0/user/expiry/status?id=65
results in:
HTTP 200
{
"expiresAt": "2022-07-03T15:22",
"tokenName": "Token name",
"description": "Longer free-text optional description about the token's purpose",
"id": 65,
"timeUntilExpiryMillis": 15541408230,
"timeUntilExpiryDays": "179"
}