Getting Started with the Kion Public API

The Kion public API enables you to programmatically interact with Kion. This requires a Kion app API key that is generated within Kion.

API key generation must be enabled in the system settings. Additionally, only admin users are allowed to generate app API keys by default. You can assign additional users permission through permission schemes. For more information, see Managing Kion App API Keys.

Administrators and users with permission can see an option in the user menu at the top right corner of the screen called App API Keys.

Generating an App API Key

1. Click the user menu in the top right corner of Kion and select App API Keys.
2. Click Add.
3. Enter a name for your app API key.
4. Click Create App API Key.
5. Click anywhere in the App API Key field to copy the token to your clipboard.

Store this token in a secure location. You cannot view the token again after closing this modal.

You can now use this token to send requests via the Kion public API. The app API key must be added to a request header with a name of Authorization and a value in this format: Bearer YOURTOKENHERE.

Swagger

Swagger is an API standard that makes it easy to document and test an API. There are two UIs for Swagger included with Kion:

• https://YOUR-CLOUDTAMER-URL/swagger . This UI is for testing API endpoints.
• https://YOUR-CLOUDTAMER-URL/swagger/redoc . This UI is for reading about API endpoints.

You can also reach either of these by clicking the user menu in the top right corner of Kion and selecting App API Keys. Use the dropdown menu in the top right to select which UI you want to go to.

When you see the account_id field, this references the ID of the account in Kion , not the 12 digit AWS account number.

To test with the Swagger UI:

1. Navigate to: https://YOUR-CLOUDTAMER-URL/swagger
2. Click Authorize.
3. Enter Bearer YOURTOKENHERE. Replace “YOURTOKENHERE” with your app API key token.
4. Click Authorize.
5. Click Close.

You can test any endpoint by selecting it and clicking Try it out.  An easy starting point would be a GET endpoint, since most don’t require any input.

CURL

It’s easiest to use CURL or a REST client like ARC or Postman to interact with the API. These instructions use CURL for making requests, since many systems have CURL installed by default.

The examples below are not the only available API commands. You can get the CURL commands directly from the Swagger UI by clicking the Execute button under each endpoint.

The app API key must be added to a request header with a name of Authorization and a value in this format: Bearer YOURTOKENHERE.

Sample GET Request

            curl -X GET "https://YOUR-CLOUDTAMER-URL/api/v3/idms" \
-H "accept: application/json" \
-H "Authorization: Bearer YOURTOKENHERE"

200 Response

            {  
      "status":  200,  
      "data":  [  
          {  
              "id":  1,  
              "name":  "Internal Directory",  
              "password_expiration":  90,  
              "idms_type_id":  1  
          }  
      ]  
}

401 Response

            {  
      "status":  401,  
      "message":  "Unauthorized"  
}

Sample POST Request

            curl -X POST "https://YOUR-CLOUDTAMER-URL/api/v3/user" \
-H "accept: application/json" \
-H "Authorization: Bearer YOURTOKENHERE" \
-H "Content-Type: application/json" \
-d "{ \"email\": \"jdoe@example.com\", \"first_name\": \  
\"John\", \"idms_id\": 1, \"last_name\": \"Doe\", \  
\"mfa\": 1, \"phone\": \"123-555-4567\", \  
\"user_group_ids\": [ 1 ], \"username\": \"jdoe\"}"

200 Response

            {  
    "status":  201,  
    "record_id":  "13"  
}

400 Response

            {  
      "status":  400,  
      "message":  "user already exists"  
}