CoreStack External APIs

Overview

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

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

Before drilling into API reference, it is important to understand some key fundamentals.

CoreStack Organization – Tenant Structure

CoreStack out of the box supports multi-tenancy. In enterprises and IT organizations, there will be multiple departments. Associates & resources under each department are to be isolated from each other. The isolation is not only needed for financial accounting but also for security and management. Though the associates can have access to multiple departments, but their permissions will vary between departments.

In an enterprise, there can be multiple departments such as Operation, Finance, R&D and these can be considered as tenants in CoreStack. Below diagram shows the sample mapping for a similar setup:

In an IT organization, there can be multiple teams such as QA, Engineering, DevOps and these can be considered as tenants in CoreStack. Below diagram shows the sample mapping for a similar setup:

For detailed information about Accounts, Tenants, Users & Roles, please refer our user guide.

CoreStack API Modules

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 & Authorization

Introduction

To access 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. Auth token can be generated using the Authorization API by providing the Access Key and Secret Key.

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

All other CoreStack API calls require Username & Auth-token. 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, hence providing tenant ID is mandatory to perform API operations under the corresponding tenant.

Refer 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 & 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 Access Key & Secret Key

In order to access CoreStack APIs, user must have Access Key & Secret Key. Follow the steps provided below to generate Access Key & Secret Key:

1. Login to CoreStack as ops_admin
2. Navigate to Users Page
   a. Click the settings icon at the top right
   b. Click Users from the menu
   c. Users page will be displayed 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” at the bottom right
7. Click “Create User”
8. The user receives an activation email to create a password for the newly created user account.

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

Regenerate Access / Secret Keys

Perform the following steps to regenerate access key & 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 at the top right
   b. Click Users from the menu
   c. Users page will be displayed 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” on the right pane
5. This section will have the Access Key and Valid Till information along with a “REGENERATE KEY” button
6. Clicking on “REGENERATE KEY” button will overwrite the existing key and creates a new key. The old keys will become invalid after regenerating the keys.
7. The user will receive an email with the regenerated Access Key & Secret Key

How to Retrieve 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 authentication token generated using AuthToken API and access CoreStack external APIs.

Construct an API request similar to the one as explained below for the request 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

Following are 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.

Supported Data Types – Request/Response JSON Data Types

CoreStack supports widely used data types as part of the request/response body.

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 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

To view the list of APIs, click here.