Overview
itopia provides a RESTful interface for the Cloud Automation Stack; this interface, referred to as the CAS API, allows customers to programatically access all actions available in the CAS Admin Console (cas.itopia.com), allowing for customized automation of provisioning and management tasks.
This article provides you with the information needed to get started with the CAS API. Additional articles in the Developers section provide you with examples and sample code to perform common tasks.
Accessing the CAS API
The current iteration of the CAS API is published at https://cas-rest.itopia.com/api/v2/. A Google Docs guide to common API usage scenarios is available here. You can also browse the full list of endpoints and functions using Swagger: https://cas-rest.itopia.com/swagger.
Authentication
Using the CAS API requires all requests to be authenticated. CAS API uses the bearer token model with JSON Web Tokens (JWT). tokens can be generated in one of two ways:
Generating a CAS API key in the CAS Admin Console and constructing a JWT manually. The CAS API key can be assigned unique permissions and scope and is not bound to any specific user.
Performing a login request against the API using the credentials of a CAS administrator for your deployment or organization. This login request will return a JWT that can be included in subsequent requests, and the token will have the same permissions and scope as the credentials provided.
API Key Method (Recommended)
The CAS admin console allows you to generate API keys, each with its own permissions and scope. The API keys can be used to construct custom JWTs as needed by your application. You can learn more about building a JWT at jwt.io.
Generate the API Key
Log in to the CAS Admin Console as a member of the Deployment Owner or Organization Owner roles.
Click on your username in the top-right corner and select Manage Organization.
In the Organization Settings, select the API Keys tab.
Click Create.
Specify the following fields:
Description - Required. A useful description of the purpose of the API key. Only visible in the Admin Console
Assign admin role - Select the admin role to assign to the API key. This can be a built-in role or a custom role (visible on the Admins tab of the Organization Settings).
Grant access to: - Select whether the API key should be granted the selected role on all deployments in the organization or only on specific deployments.NOTE: If you select the Organization Owner role, this setting has no effect and the API key has full access to all deployments in the organization.
Click Create.
The API key will be generated and displayed only once; after the dialog is closed, this key cannot be viewed again. Make sure to copy the key and store it in a secure location.
JWT Structure
The JWT should contain the following information:
Header: ALGORITHM & TOKEN TYPE |
{
"type": "JWT"
} |
Payload: DATA |
{
"iat": timestamp,
"exp": timestamp,
"organizationId": integer,
"deploymentId": integer
} |
Field | Type | Description |
aud | string | This is a constant value. Must be set to "Itopia" |
iat | timestamp | The "issued at" timestamp from which the token is considered valie |
exp | timestamp | The "expiration" timestamp after which the token is no longer valid |
organizationId | integer | The organization identifier |
deploymentId | integer | (Optional) The deployment identifier. Use this if the API key is scoped to multiple deployments and you want to ensure that the token is only valid for a specific deployment |
Construct the token |
base64UrlEncode(header) + "." + base64UrlEncode(payload), [API Key]
) |
Authenticated Header Example
Once a JWT is acquired using either of the methods above, the token should be included in all requests to the CAS REST API. For example, to get a list of VM instances in the deployment, you would use the following:
GET https://cas-rest.itopia.com/api/v2/deployments/[deploymentId]/cloudInstances |
and include the following header in the request:
Authorization: Bearer [JWT token] |
Login Method
To use the login method, you can send an unauthenticated request to the accounts/login/ endpoint with the username and password of a CAS admin account for which to generate a JWT. The token is preconstructed and returned along with an expiration timestamp; tokens are valid for one hour.
HTTP Request
Request Body
Parameter | Type | Description |
username | string | CAS admin username
Format :
|
password | string | Plaintext password |
Response Body
If successful, the response contains data with the following structure:
JSON representation |
{
"Cielo_Expiration_Token": integer
} |
Field | Type | Description |
Cielo_Token | string | Authentication token to be used for itopia API calls |
Cielo_Expiration_Token | integer | One hour expiration time |
The Cielo_Token value is the JWT bearer token that should be included in the header on every itopia API call.
NOTE: CAS admin users that do not have a password in CAS (i.e. users that rely on Google or Microsoft SSO) cannot be used with this method. |
Next Steps
Review the examples provided in the itopia CAS API Documentation, or browse the CAS REST Swagger documentation: https://cas-rest.itopia.com/swagger.