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

1. Log in to the CAS Admin Console as a member of the Deployment Owner or Organization Owner roles.
2. Click on your username in the top-right corner and select Manage Organization.
3. In the Organization Settings, select the API Keys tab.
4. Click Create.
5. 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.
6. Click Create.
7. 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:

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:

and include the following header in the request:

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

Response Body

If successful, the response contains data with the following structure:

The Cielo_Token value is the JWT bearer token that should be included in the header on every itopia API call.

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.