Public API Guide

Follow

This guide will show you how to interact with the cloudtamer.io public API. The API will allow you to programmatically interact with cloudtamer.io to support any type of automation you need.

Below are the steps in this guide:

  1. Configure API access settings, which includes enabling App API Key Generation.
  2. Assign the global permission Manage Own App API Keys to a role.
  3. Assign users and groups to the role via the global permission scheme.
  4. Generate an app API key.
  5. Use the Swagger UI to test the API.

Common Issues

These are the common issues we’ve seen when using the API:

  • When you add the app API key to the Swagger UI by clicking Authorize, be sure to prefix it with the word: Bearer. There should be a space between Bearer and your app API key. We pre-fill this for you, so you should only need to click in the Value field and type in the key.
  • When you see the account_id field, this references the ID of the account in the cloudtamer.io application, not the 12 digit AWS account number.

Configure API Access Settings

To enable the generation of App API Keys by users, you need to enable it in the cloudtamer.io global settings. Once it is enabled, administrators will be able to generate their own App API Keys, but non-admin users will not be able to until they are explicitly given permission. You can also configure other API access settings in the same place.

To enable API key generation and configure the settings:

  1. In the left navigation menu, click Settings > All Settings.
  2. Click the App API Access tab under Application Settings.
  3. In the API Key Limit Per User field, set the number of app API keys allowed per user. The minimum value is 1 and the maximum value is 10. The default value is 2.
    • If you set the key limit to a value that is less than the number in use by a user, you will get an alert that says App API Key limit per user must be at least [value]. Click Learn More for the option to Download User API Key Report, which shows you which users have more keys than the number specified. Reduce their API keys to adjust the key limit (see the "Delete an API Key" section below).
  4. Set the App API Key Generation toggle to ON.
  5. Set the App API Key Lifespan (days) toggle to ON and set the value in the field below it if you want the app API keys to automatically expire after a certain number of days. Users will receive notifications a few days prior to their keys expiring.
  6. Click Update App API Access Settings to save the settings.

Administrators will now see a new option on the user menu at the top right corner of the screen called App API Keys.

Settings-_-App-API-Access-cloudtamer-io.png

Overview-cloudtamer-io__9_.png

Give Non-Admin Users Access to Generate App API Keys

By default, users are not allowed to generate app API keys. You must assign the permission to a role in the global permission scheme and then give the users access through the Global Permissions User Mapping tab in the global settings.

To add the permission to a role in the global permission scheme:

  1. In the left navigation menu, click Settings > Permissions.
  2. Click the ellipsis menu next to the Global Permissions Scheme and click Edit.
  3. Find the permission Manage Own App API Keys and assign it to the desired role.
  4. To save, click the Update Permission Scheme button at the bottom of the page.

Edit-Permission-Scheme-cloudtamer-io__3_.png

Now that the permission is assigned to a role, you can assign users or groups to the role:

  1. In the left navigation menu, click Settings > Permissions.
  2. Click the Global Permissions tab.
  3. Find the role chosen in the steps above. It should have the Manage Own App API Keys permission.
  4. Assign the Users or a User Groups to the role using the drop-down menus.
  5. To save, click the Save button at the bottom of the page.

Permissions-cloudtamer-io__2_.png

Now, the users will see a new option on the user menu at the top right corner of the screen called App API Keys.

Overview-cloudtamer-io__9_.png

Generate/Delete an App API Key

The App API Key is a token that may or may not expire depending on the App API Key Lifespan set in the global settings. The App API Key should be added to a request header with a name of “Authorization” and a value in this format: “Bearer YOURTOKENHERE”.

Generate an API Key

To generate an App API Key:

  1. In the top right user menu, click your name > App API Keys.
  2. Click the Add button.
  3. Enter in a name for your App API Key and click the Create App API Key button.
  4. Tap the field with the asterisks to automatically copy the token to your clipboard.
  5. Click the Close button.

Save the token securely. You cannot view the token again after you close it.

API-Keys.png

API-Keys__2_.png

Delete an App API Key

Should you need to delete an API key, you can do so in the same place. Users with the Manage App API Keys permission (in the global permission scheme) can delete keys for all users. Users with the Manage Own App API Keys permission can delete their own keys, but not other users' keys.

To delete an API key:

  1. In the user menu on the top right, click your name > App API Keys.
  2. Click the ellipsis menu next to the API key and select Delete.
  3. Confirm deletion by pressing Delete on the pop-up modal.

The API key is now permanently deleted.

Test the API using Swagger

Swagger is an API standard that makes it easy to document and test an API. There are two UIs for Swagger included with your versions of cloudtamer.io 2.11 and greater:

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

To test with the Swagger UI:

  1. Navigate to: https://YOUR-CLOUDTAMER-URL/swagger.
  2. Click the Authorize button.
  3. Type in the textbox: Bearer YOURTOKENHERE. Replace “YOURTOKENHERE” with your App API Key token.
  4. Click the Authorize button.
  5. Click the Close button.
  6. You can now click on any of the endpoints and click Execute.  An easy starting point would be a “GET” endpoint, since most don’t require any input.

Swagger-UI.png

Sample Requests with 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 API commands, but they do provide guidance on how to interact with them. You can also get the CURL commands directly from the Swagger UI by clicking the Execute button under each endpoint.

Request

This is a GET request to retrieve a list of the identity management systems (IDMS) in the application.

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

200 Response

This is a successful 200 JSON response.

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

401 Response

This is an unauthorized 401 JSON response.

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

Request

This is a POST request to create a new user in the application.

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

This is a successful 200 JSON response.

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

400 Response

This is a bad request 400 JSON response.

{
    "status": 400,
    "message": "user already exists"
}
Was this article helpful?
2 out of 2 found this helpful