CoreStack External APIs

Getting started guide to use CoreStack 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.

S.No.

Module Name

Module Description

1

Authorization

These APIs provide a secure authorization mechanism to access the CoreStack APIs.

2

Identity

These APIs will provide you the ability to manage the CoreStack account-related identity and access information such as tenants, users, roles and permissions, passwords, etc.

3

Guardrails

These APIs will help you to create, manage, and execute the guardrail policies using CoreStack on your cloud accounts. The policies can be used to assess, audit, and evaluate the configurations of your cloud resources, so that those resources stay compliant with your corporate standards and service level agreements.

4

Account Governance

These APIs allow you to manage and set up assessments of your cloud accounts against CoreStack cloud governance pillars.

5

Operations

These APIs will provide you the ability to operate and manage your cloud resources efficiently using various features such as automation, monitoring, notifications, activity tracking.

6

Security

These APIs will provide you the ability to manage the security governance of your cloud accounts and identify the security vulnerabilities & threats and resolve them.

7

Cost

These APIs will provide you the ability to create a customized controlling mechanism that can control your cloud expenses within budget and reduce cloud waste by continually discovering and eliminating inefficient resources.

8

Access

These APIs will provide you the ability to configure secure access of resources in your cloud environment and protect the users’ data & assets from unauthorized access.

9

Resource

These APIs will provide you the ability to define, enforce, and track the resource naming and tagging standards, sizing, and their usage by regions. It also enables you to follow consistent & standard practices pertaining to resource deployment, management, and reporting.

10

Compliance

These APIs will provide you the ability to assess your cloud environment for its compliance status against standards and regulations that are relevant to your organization – ISO, NIST, HIPAA, PCI, CIS, FedRAMP, AWS Well-Architected framework, and custom standards.

11

Self Service

These APIs will provide you the ability to configure a simplified self-service cloud consumption model for end users that are tied to approval workflows. It enables you to automate repetitive tasks and focus on key deliverables.

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.

Header

Value

Content-Type

application/json

X-Auth-User

Username of the tenant

X-Auth-Token

Token generated as part of AuthToken API

📘

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.

Verb

Operation

GET

To List all resources or Get a specific resource. Request Body is not supported.

PUT

To Update properties of existing resources. Also used to perform specific actions on an existing resource.

POST

To Create new resource and in some cases used for fetching resources with complex parameters which cannot be accommodated in GET method.

DELETE

To Delete one or more existing resources.

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.

Response Code

Description

200 – Ok

The operation was successful, and a response has been returned (GET and PUT requests)

201 – Created

The operation was successful, the posted entity has been created and requested information is returned in the response-body (POST request)

204 – No Content

The operation was successful, the requested entity has been deleted and therefore there is no response-body returned (DELETE request)

401 – Unauthorized

The operation failed. The operation requires Authentication headers to be set. If this was present in the request, there are chances that supplied credentials are not valid or the user is not authorized to perform this operation.
X-Auth-User & X-Auth-Token headers should have valid credentials.

403 – Forbidden

The operation is forbidden and should not be re-attempted. This does not imply an issue with authentication, it’s an operation that is not allowed.
Example: deleting a task that is part of a running process is not allowed and will never be allowed, regardless of the user or process/task state

404 – Not Found

The operation failed. The requested resource was not found.

405 – Method Not Allowed

The operation failed. The HTTP method used is not allowed for this resource. Example: trying to update (PUT) a deployment-resource will result in a 405 status.

409 – Conflict

The operation failed. The operation causes an update of a resource that has been updated by another operation, which makes the update no longer valid. Can also indicate a resource that is being created in a collection where a resource with that identifier already exists

500 – Internal Server Error

The operation failed. An unexpected exception occurred while executing the operation. The response-body contains needed details about the error

Supported Data Types – URL Query Parameters

CoreStack supports widely used data types as part of the URL query parameters.

Type

Format

String

Plain text parameters. Can contain special characters, numerals and alphabets with proper URL encoding.

Integer

Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647

Long

Parameter representing a long value. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807

Boolean

Parameter representing a Boolean value. Can be either true or false. Any other values other than these two, will be considered as a string input throwing 405 – Bad request response

Date

Parameter representing a date value. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) with both time and date values (e.g., 2013-04-03T23:45Z)

Supported Data Types – Request/Response JSON Data Types

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

Type

Format

String

Plain text parameters

Integer

Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647

Long

Parameter representing a long value. Can only contain numeric non-decimal values, between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807

Boolean

Parameter representing a Boolean value. Can be either true or false. Any other values other than these two, will be considered as a string input throwing 405 – Bad request response

Date

Parameter representing a date value, using a JSON text. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (e.g., “2013-04- 03T23:45Z”)

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.


Did this page help you?