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:
- Login to CoreStack as ops_admin
- 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 - Click ‘+‘ icon to add a new user
- Fill in the necessary details and provide a valid email address
- The role and tenant access determines the access control for the user and the APIs they can access.
- Select the checkbox “Generate API Access” at the bottom right
- Click “Create User”
- 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:
- Login to CoreStack as the user that has the privilege to manage users (e.g., ops_admin)
- 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 - Select the user for whom the API keys need to be regenerated
- Expand the section “API Access” on the right pane
- This section will have the Access Key and Valid Till information along with a “REGENERATE KEY” button
- 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.
- 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. |
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. |
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.
Updated 8 months ago