Skip to main content
Getting Started with the CAS REST API
F
Written by Fegeins Louis
Updated over a week ago

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:

Header: ALGORITHM & TOKEN TYPE

{
"alg": "HS256",

"type": "JWT"

}

Payload: DATA

{
"aud": "Itopia",

"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


HMACSHA256(

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_Token": string,

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

Did this answer your question?