Overview

CoreStack offers a wide range of REST APIs to integrate with your product or external services/tools programmatically. With REST API support it's possible to integrate with almost all of the programming languages, while the integration varies from one language to the other.

CoreStack's API guide not only provides information about the REST APIs available in cURL format but also provides the code snippets for widely-used programming languages, such as Java, Python, JavaScript, PHP, and so on.

Before drilling into our API reference, it's important to understand some key fundamentals.

CoreStack Organization – Tenant Structure

CoreStack out of the box supports multi-tenancy. In enterprises and IT organizations, there are bound to be multiple departments. Associates and resources under each department often need to be isolated from each other. This isolation is not only needed for financial accounting but also for security and management purposes. Associates can have access to multiple departments, but their permission levels will likely vary between departments.

In an enterprise, some common departments include Operations, Finance, and R&D -- these can also be considered as tenants in CoreStack.

The below diagram shows a sample mapping for a similar setup:

In an IT organization, some common teams include QA, Engineering, and DevOps -- these can also be considered as tenants in CoreStack.

The below diagram shows a sample mapping for a similar setup:

For more detailed information about Accounts, Tenants, Users, and Roles, please refer to our other user guides.

CoreStack API Modules

The CoreStack API is organized around the following modules. Please note that this is very similar to the CoreStack cloud governance pillars around OSCAR, compliance, and self-service.

Authentication and Authorization

Introduction

To access the CoreStack API, you will need an auth token and username.

The auth token is a short-lived token that provides authorization to perform API operations. An auth token can be generated using the Authorization API by providing the Access Key and Secret Key.

The Access Key and Secret Key are the access credentials you would need to generate the authorization token. The AuthToken API is used to generate an Auth Token by providing these access credentials.

Once the user is terminated or suspended in the CoreStack portal, the associated user's "Access Key" and "Secret Key" will no longer be working. If the user authentication is enabled using SSO, the user will be created in the CoreStack portal but the authentication will be using the user organization LDAP. Once the user is terminated or suspended in the organization LDAP, the user can longer authenticate to access the CoreStack portal. In this case, the respective user's "Access Key" needs to be deleted in the CoreStack portal.

All other CoreStack API calls require a Username and Auth-token. A few API calls, in addition, may require TenantID and/or Account ID as well. All these values are available in the authorization API response.

A CoreStack account can have multiple tenants, which is why providing a tenant ID is mandatory in order to perform API operations under the corresponding tenant.

Refer to the API guide for the detailed information about AuthToken (Authentication) API.

Authentication Headers

The following authentication headers must be available as part of all API requests:

📘

Note:

X-Auth-User and X-Auth-Token are required for all API operations -- except the Authentication API.

Sample API Request with Authentication Headers

The following example demonstrates how to use authentication headers and retrieve the list of all tenants within a CoreStack Account.

curl -X GET -H “X-Auth-Token: [[Access Token]]” -H “X-Auth-User: [[username]]” https://api-discover.corestack.io/v1/tenants

curl -X GET -H “X-Auth-Token: abcedefghijklmno34567890” -H “X-Auth-User: cs_user” https://api-discover.corestack.io/v1/tenants

How to get the Access Key and Secret Key

In order to access CoreStack APIs, a user must have an Access Key and Secret Key.

Follow the steps provided below to generate an Access Key and Secret Key:

1. Login to CoreStack as ops_admin.
2. Navigate to the Users Page:
   a. Click the settings icon in the top-right.
   b. Click Users from the menu.
   c. The Users page will be displayed along with the list of users available under the CoreStack Account.
3. Click ‘+‘ icon to add a new user.
4. Fill in the necessary details and provide a valid email address.
5. The role and tenant access determines the access control for the user and the APIs they can access.
6. Select the checkbox “Generate API Access” in the bottom-right.
7. Click Create User.
8. The user will receive an activation email to create a password for the newly created user account.

Once it is activated, the user account will be successfully created. The user also receives an email with the API URL, Access Key, and Secret Key.

Regenerate Access/Secret Keys

Perform the following steps to regenerate the Access Key and/or Secret Key:

1. Login to CoreStack as the user that has the privilege to manage users (e.g., ops_admin).
2. Navigate to Users Page:
   a. Click the settings icon in the top-right.
   b. Click Users from the menu.
   c. The Users page will be displayed along with the list of users available under the CoreStack Account.
3. Select the user for whom the API keys need to be regenerated.
4. Expand the section API Access in the right pane.
5. This section will have the Access Key and Valid Till information along with a “REGENERATE KEY” button.
6. Clicking on the “REGENERATE KEY” button will overwrite the existing key and create a new key. The old keys will become invalid after regenerating.
7. The user will receive an email with the regenerated Access Key and Secret Key.

How to Retrieve the Authorization Token

Once you have the access credentials, you can create an authorization token using the Authorization API.

The following code demonstrates how to retrieve authorization token using AuthToken API.

Use the following AuthToken API to generate an authorization token:

curl -X POST -d  {"access_key":"[[AccessKey}}", "secret_key":"SecretKey"} -H "Content-Type: application/json" https://api-discover.corestack.io/v1/auth/tokens

curl -X POST -d  {"access_key":"a1b2c3d4e5f6g7h8i9j", "secret_key":"abcdefghijk1234567890"} -H "Content-Type: application/json" https://api-discover.corestack.io/v1/auth/tokens

How to Use the Authorization Token

The following example demonstrates how to use the authentication token generated using the AuthToken API and access CoreStack's external APIs.

Construct an API request similar to the one explained below for requesting API operation. The following example explains how to retrieve the list of all tenants within a CoreStack Account:

curl -X GET -H “X-Auth-Token: [[Access Token]]” -H “X-Auth-User: [[username]]” https://api-discover.corestack.io/v1/tenants

curl -X GET -H “X-Auth-Token: abcedefghijklmno34567890” -H “X-Auth-User: cs_user” https://api-discover.corestack.io/v1/tenants

📘

Note:

All the CoreStack APIs can be tried virtually in the Developer Portal.

HTTP Verbs

The following table contains the REST API HTTP Verbs supported by CoreStack.

Response Codes

The following table provides a list of response codes that can be expected in response to an API request, and describes the result of an API operation.

Supported Data Types – URL Query Parameters

CoreStack supports widely used data types as part of the URL query parameters, as shown in the table below:

Supported Data Types – Request/Response JSON Data Types

CoreStack supports widely used data types as part of the request/response body, as shown in the table below:

Other Information

Pagination

Pagination applies to only LIST actions such as ListTenants, ListUsers and so on.

Query Parameter Usage

'Limit' in query parameter is used to limit the number of records in the response, whereas 'page' in query parameter is used to provide the page number.

http://<list_api_endpoint>?limit=25&page=2

Actions not supported through API

The following actions are not supported by CoreStack through APIs.

• CloudAccount API actions for Azure

📘

Note:

To view the list of APIs, click here.