CloudLabs provides hands-on lab environments for individual learners and organizations for events and workshops. CloudLabs REST API provides end points to create and manage your own labs and environments.

Following are the supported authentication methods:

1. Authentication on behalf of Azure AD App (using client credentials).

2. Authentication on behalf of Azure AD User (Azure AAD Authentication).

3. Authentication on behalf of Azure AD User (OAuth 2.0 resource owner Password credentials Grant). Few entities associated with CloudLabs:

4. Tenant: Partner/Customer who is authorized by Spektra Systems to create/manage labs in CloudLabs Portal.

5. Lab: It can be a classroom/workshop with pre-configured template/subscription for lab environments.

6. Attendee: End user who is going to use the lab environment.

7. Deployment: Environment setup in Azure.

Before trying out our API, please make sure you have a valid apiURL, api-version, Ocp-Apim-SubscriptionKey, and data required for authentication.

Table of Contents

Authentication on behalf of Azure AD App 3

Get Tenants 4

Get Labs 4

Get Lab By Id 7

Add Deployments 9

Get Lab Summary 9

Add Attendee 10

Add Attendee (Anonymous) 12

Get Attendee Deployment 13

Launch Lab Environment 17

Get Attendees 18

Get Attendee List Report 19

Check Signup Availability 20

Modify Attendee Settings 20

Delete deployment 21

Create Activation Codes 22

Get Activation Codes 23

Schedule Start VM 24

Schedule Stop VM 25

Clone Lab 26

Exceptions 26

Meta data – Attendee Status 27

Authentication on behalf of Azure AD App

Here Authentication is done in the context of an Azure AD App provided by Spektra Systems. This will be unique for a tenant. For accessing any of the endpoints mentioned in this document, you need to pass authorization token and Ocp-Apim-Subscription-Key in the Headers. Directory Id, Client Id, Client Secret and Scope will be shared by Spektra Systems.

GET  https://login.microsoftonline.com/{directoryId}/oauth2/v2.0/token Headers

Request Body

Sample Response Status Code: 200 Body: JSON Object

{

"token_type": "Bearer", "expires_in": 3599,

"ext_expires_in": 3599,

"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InBpVmxsb1FEU01LeGgxbTJ5Z3FHU1ZkZ 0ZwQSIsImtpZCI6InBpVmxsb1FEU01LeGgxbTJ5Z3FHU1ZkZ0ZwQSJ9.eyJhdWQiOiJhcGk6Ly8wMGMwNjVkMi1jNmQwLTRhZm YtYjJjNy1kOTg2YzllN2Y3ZTAiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9iYWQ1MmY2Mi0wOTU3LTQ3ZTEtYjA0 Ny04YTg3NzhlMjdiNjEvIiwiaWF0IjoxNTc3Nzc1MzA3LCJuYmYiOjE1Nzc3NzUzMDcsImV4cCI6MTU3Nzc3OTIwNywiYWlvIj oiNDJWZ1lPaDdIK2hkODRtWGVmN2JTLy91ZGpuSEFnQT0iLCJhcHBpZCI6ImY3ZTNhZDEyLTU4YmEtNGM2MC1iMjkxLWFkMWRl

NTQ3OWY2NiIsImFwcGlkYWNyIjoiMSIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0L2JhZDUyZjYyLTA5NTctNDdlMS 1iMDQ3LThhODc3OGUyN2I2MS8iLCJvaWQiOiIwZWQxZWY5Yi03NTY0LTRiYmUtYWRiZC02MDVhNDY5ZWU5ZWMiLCJyb2xlcyI"

}

Get Tenants

This endpoint returns information (name, tenantId) about tenants associated with user/app from which request is originated. TenantId retrieved in the response is mandatory for all other requests.

GET {apiURL}/api/tenants URI Parameters

Headers

Sample Response Status Code: 200 Body: JSON Object

{

"previousLink": null, "totalItems": 1, "value": [

{

"name": "Contoso",

"tenantId": "4a203453-4c37-4874-8c4b-96d865f8371a"

}

],

"nextLink": null

}

Get Labs

This endpoint returns all active labs associated with requested tenant. LabId in the response, can be used in all scenarios related to a lab.

GET {apiURL}/api/tenants/{tenantId}/labs URI Parameters

Sample Response Status Code: 200 Body: JSON Object

{

"previousLink": null, "totalItems": 2, "value": [

{

"name": "Azure Functions & Logic App Serverless", "labId": "8352c78d-5c1b-4527-9e0b-435a8ff884e1",

"labCode": "AZ001",

"labType": "demo",

"launchUrl": "https://cloudlabs-manage.azurewebsites.net/#/odl/8352c78d-5c1b-45279e0b-435a8ff884e1",

"description": "Test", "deploymentMaxIdleTime": "1H",

"usesRdp": false,

"status": "registration_open",

"approvalStatus": "registration_activation_code_required", "maxNumberOfAttendees": null,

"maxNumberOfRetake": "5", "expiryDate": "2019-12-31T00:00:00",

"ownerEmail": "akash@spektra.com", "allowPersonalEmailForRegistration": true, "allowAttendeeToDeleteEnvironment": false, "enableStandByDeployments": true, "regions": [

"West Central US"

],

"tags": [

"azure"

],

"jobRoles": [

"Application Developer", "Architects",

"Business Analyst"

],

"audiences": [

"Data Developer", "Enterprise Developer"

],

"topics": [

"Administration", "Application Innovation"

],

"levels": [

Headers

"Intermediate"

],

"products": [

"Apache Spark", "Application Gateway"

]

},

{

"name": "Migrating SQL Database to Azure", "labId": "c12d590c-95f2-42c8-bafe-1af312cf206d", "labCode": "sdktest",

"labType": "self-paced",

"launchUrl": "https://cloudlabs-dev.azurewebsites.net/#/launch/c12d590c-95f2-

42c8bafe-1af312cf206d",

"description": "Please sign-up to get access.", "deploymentMaxIdleTime": "1H",

"usesRdp": false,

"status": "registration_open", "approvalStatus": "registration_required", "maxNumberOfAttendees": null, "maxNumberOfRetake": "",

"expiryDate": "2019-12-31T00:00:00",

"ownerEmail": "akash.premaraj@spektrasystems.com", "allowPersonalEmailForRegistration": true, "allowAttendeeToDeleteEnvironment": false, "enableStandByDeployments": true,

"regions": [

"West Central US"

],

"tags": [

"azure"

],

"jobRoles": [],

"audiences": [],

"topics": [],

"levels": [],

"products": []

}

],

"nextLink": null

}

Get Lab By Id

This endpoint returns data specific to a lab.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId} URI Parameters

Sample Response Status Code: 200 Body: JSON Object

{

"name": "Azure Functions & Logic App Serverless", "labId": "8352c78d-5c1b-4527-9e0b-435a8ff884e1",

"labCode": "sdktest", "labType": "demo",

"launchUrl": "https://cloudlabs-manage.azurewebsites.net/#/odl/8352c78d-5c1b-45279e0b-435a8ff884e1",

"description": "Test", "deploymentMaxIdleTime": "1H",

"usesRdp": false,

"status": "registration_open",

"approvalStatus": "registration_activation_code_required", "maxNumberOfAttendees": null,

"maxNumberOfRetake": "5", "expiryDate": "2019-12-31T00:00:00",

"ownerEmail": "akash@spektra.com", "allowPersonalEmailForRegistration": true, "allowAttendeeToDeleteEnvironment": false, "enableStandByDeployments": true, "regions": [

"West Central US"

],

"tags": [

"azure"

],

"jobRoles": [

"Application Developer", "Architects",

"Business Analyst"

],

"audiences": [

"Data Developer", "Enterprise Developer"

],

"topics": [

"Administration", "Application Innovation"

],

"levels": [

"Intermediate"

Headers

],

"products": [

"Apache Spark", "Application Gateway"

]

}

Add Deployments

This can be used to create pre-created lab environments for attendees before the lab begins. Number of environments/deployments required needs to be mentioned in the request body.

POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/deployments URI Parameter

Headers

Request Body (JSON)

Sample Response

Status Code: 204 No Content Body:

Empty

Get Lab Summary

Before starting a lab, this endpoint can be used to check the lab deployment status, user count, etc. GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/summary

URI Parameter

Sample Response Status Code: 200 Body: JSON Object

{

"initiatedDeploymentCount": 1,

"standByDeploymentCount": 0

}

Add Attendee

This endpoint can be used to add an attendee to a lab.

POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees URI Parameters

Headers

Headers

Request Body (JSON)

Sample Response Status Code: 200

Body: JSON Object

{

"attendeeId": "9a6c5f31-141a-4a19-921f-56ab091175ca",

"labLaunchURL": "https://cloudlabs-manage.azurewebsites.net/#/odl/c12d590c-95f2-42c8-bafe-1af312cf206d/9a6c5f31-141a-4a19-921f-56ab091175ca"

}

This launch URL can be given to attendee. Once this is viewed in a browser, attendee will get either a launch button (if environment is not launched previously) or deployment details/VM + Guide experience.

Add Attendee (Anonymous)

This endpoint can be used to add an anonymous attendee to a lab. Since the attendee’s name and email address are optional, the request body can be left empty. Once the launch URL is opened in a browser, the environment will launch automatically. This is supported only if the ODL approval type is configured with “Anonymous” approval type.

POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees URI Parameters

Headers

Request Body (JSON) Empty

Sample Response Status Code: 200

Body: JSON Object

{

"attendeeId": "9a6c5f31-141a-4a19-921f-56ab091175ca",

"labLaunchURL": "https://cloudlabs-manage.azurewebsites.net/#/odl/c12d590c-95f2-42c8-bafe-1af312cf206d/9a6c5f31-141a-4a19-921f-56ab091175ca"

}

Get Attendee Deployment

This can be used to get current deployment of an attendee. If the deployment status is not “Succeeded”, this endpoint needs to be called after some time, to get new status.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees/{attendeeId}/deployments URI Parameter

Headers

Sample Response (for VM only scenario) Status Code: 200

Body: JSON Object

{

“attendeeId”: “68141a-4a19-921f-56ab091175ca”

“userName”: “odl_user_141589@cloudlabsaioutlook.onmicrosoft.com”, “password”: “htzj01SBX*u3”,

“deploymentStatus”: “Succeeded”, “rdpOverHttpsURL”: “https://rdp-

141491o3qtnneegkgum.mscloudlabs.ai/guacamole/#/?userName=USERNAME&uri=rdp:%2F%2Fdemouser:d emopass$123@labvmrxo7 m6bgpwlri.eastus.cloudapp.azure.com:3389%2F%3Fsecurity%3Dany%26ignore-cert%3Dtrue%26disableaudio%3Dtrue”,

“labGuideURL”: null,

“labLaunchURL”: “https://manage.cloudlabs.ai/#/odl/acec4a96-62cc-404a-825aec7b34800745/445b7365-4589-4f2d-b925-ee399d3cb025”,

“servicePrincipalDisplayName”: “https://odl_user_sp_141911”,

“servicePrincipalApplicationId”: “c2f7349a-1a42-4651-b644-893b15515yui”, “servicePrincipalAppObjectId”: “f01642b0-aae9-49df-b06b-02f368ac1678”,

“servicePrincipalObjectId”: “f987fb27-1ecb-4b93-9152-5a94f6af9e0c”, “servicePrincipalKey”: “zerk69JMM*BR”,

“properties”: [], “resourceGroups”: [

{

“resourceGroupName”: “ODL-vm-141589”, “resourceGroupRegion”: “West US”,

“resourceGroupStatus”: “Succeeded”, “outputParameters”: [

“vmDNSName”: “labvmrxo7m6bgpwlri.eastus.cloudapp.azure.com”,

“vmUsername”: “demouser”, “vmPassword”: “demopass$123”

]

}

]

}

Sample Response (for VM + Git Document scenario) Status Code: 200

Body: JSON Object

{

“attendeeId”: “1341a-4a19-921f-56ab091175ca”

“userName”: “odl_user_97837@cloudlabsaioutlook.onmicrosoft.com”, “password”: “htzj01SBX*u3”,

“deploymentStatus”: “Succeeded”, “rdpOverHttpsURL”: “https://rdp-

141491o3qtnneegkgum.mscloudlabs.ai/guacamole/#/?userName=USERNAME&uri=rdp:%2F%2Fdemouser:d

emopass$123@labvmrxo7 m6bgpwlri.eastus.cloudapp.azure.com:3389%2F%3Fsecurity%3Dany%26ignore-cert%3Dtrue%26disableaudio%3Dtrue”,

“labGuideURL”: “https://manage.cloudlabs.ai/#/labguide/90da055c-6887-4dd5-aaff-698a7439e366/111b6e97-78fa-4771-bf33-f9f76587731”,

“labLaunchURL”: “https://manage.cloudlabs.ai/#/labenvironment/f334db39-1d40-4444-b3d5-81a0ea59edc7/777f570a-0ede-46a3-858d-ecf6545a0fb5”,

“servicePrincipalDisplayName”: null, “servicePrincipalApplicationId”: null, “servicePrincipalAppObjectId”: null, “servicePrincipalObjectId”: null,

“servicePrincipalKey”: null, “properties”: [], “resourceGroups”:

[

{

“resourceGroupName”: “ODL-vm-97837”, “resourceGroupRegion”: “West US”, “resourceGroupStatus”: “Succeeded”,

"signInLink":

"https://console.cloud.google.com/home/dashboard?project=clgcporg8-046", "signInProperty": "clgcporg8-046"

“outputParameters”: [

“vmDNSName”: “labvmrxo7m6bgpwlri.eastus.cloudapp.azure.com”,

“vmUsername”: “demouser”, “vmPassword”: “demopass$123”

]

}

]

}

Sample Response (for Git Document only scenario) Status Code: 200

Body: JSON Object

{

“attendeeId”: “78521a-4a19-921f-56ab091175ca”

“userName”: “odl_user_141000@cloudlabsaioutlook.onmicrosoft.com”, “password”: “htzj01SBX*u3”,

“deploymentStatus”: “Succeeded”, “rdpOverHttpsURL”: null,

“labGuideURL”: “https://manage.cloudlabs.ai/#/labguide/90da055c-6887-4dd5-aaff-

698a7439e366/111b6e97-78fa-4771-bf33-f9f76587731f”,

“labLaunchURL”: “https://manage.cloudlabs.ai/#/odl/acec4a96-62cc-404a-825aec7b34800745/445b7365-4589-4f2d-b925-ee399d3cb025”,

“servicePrincipalDisplayName”: null, “servicePrincipalApplicationId”: null, “servicePrincipalAppObjectId”: null, “servicePrincipalObjectId”: null,

“servicePrincipalKey”: null, “properties”: [], “resourceGroups”:

[

{

“resourceGroupName”: “ODL-vm-141000”, “resourceGroupRegion”: “West US”, “resourceGroupStatus”: “Succeeded”, “outputParameters”: []

}

]

}

Sample Response (if deployment is In-Progress) Status Code: 200

Body: JSON Object

{

“attendeeId”: “35321a-4a19-921f-56ab091175ca” “userName”: null,

“password”: null,

“deploymentStatus”: “In-Progress”, “rdpOverHttpsURL”: null, “labGuideURL”: null,

“labLaunchURL”: null,

“servicePrincipalDisplayName”: null, “servicePrincipalApplicationId”: null,

“servicePrincipalAppObjectId”: null, “servicePrincipalObjectId”: null,

“servicePrincipalKey”: null, “properties”: [],

“resourceGroups”: []

}

Sample Response (if deployment is Deleted) Status Code: 200

Body: JSON Object

{

“attendeeId”: “366441a-4a19-921f-56ab091175ca”

“userName”: “odl_user_141001@cloudlabsaioutlook.onmicrosoft.com”, “password”: “fasj01SBXreg3”,

“deploymentStatus”: “Deleted”, “rdpOverHttpsURL”: null, “labGuideURL”: null,

“labLaunchURL”: null,

“servicePrincipalDisplayName”: null, “servicePrincipalApplicationId”: null,

“servicePrincipalAppObjectId”: null, “servicePrincipalObjectId”: null,

“servicePrincipalKey”: null, “properties”: [], “resourceGroups”:

[

{

“resourceGroupName”: “ODL-vm-141001”, “resourceGroupRegion”: “West US”, “resourceGroupStatus”: “Deleted”,

“outputParameters”: []

}

]

}

Launch Lab Environment

This endpoint can be used to launch a lab environment. Note: No need to use this endpoint if it is already launched while using “Add Attendee” endpoint with auto launch.

POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees/{attendeeId} URI Parameters

Headers

Request Body (JSON)

Sample Response Status Code: 200 Body: JSON Object

*Same as “Get Attendee Deployment”

Get Attendees

This endpoint returns all attendees in a lab. Attendee in the response, can be used in all scenarios related to an attendee.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees URI Parameter

Headers

Sample Response Status Code: 200 Body: JSON Object

{

"previousLink": null, "totalItems": 2, "value": [

{

"id": "a5744afc-5f54-4a80-9c2e-13997fc9de54", "firstName": "Akash",

"lastName": "P",

"email": "akash10@spektra.com", "status": "Deleted"

},

{

"id": "9a6c5f31-141a-4a19-921f-56ab091175ca",

"firstName": "Akash", "lastName": "P",

"email": "akash8@spektra.com", "status": "Registered"

},

],

"nextLink": null

}

Get Attendee List Report

This endpoint returns all attendees in a lab. Attendee in the response, can be used in all scenarios related to an attendee.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees/reports URI Parameter

Headers

Sample Response Status Code: 200 Body: JSON Object

{

"previousLink": null, "totalItems": 4, "value": [

{

"id": "e6a0d187-7807-475d-bc4f-ac8aab5e4991", "firstName": "Santhosh",

"lastName": "sr",

"email": "Santhosh.sr@spektrasystems.com", "status": "Succeeded", "cloudDeploymentId": 131930

},

{

"id": "eff22b9f-48f9-4e7f-b28d-09f8cab8c12c", "firstName": "Akash",

"lastName": "P",

"email": "akash8@spektra.com ", "status": "Deleted", "cloudDeploymentId": 131929

}

],

"nextLink": null

}

Check Signup Availability

Before adding an attendee or if attendee wants a retake, this endpoint can be used to check the signup availability.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/checkSignUpAvailability URI Parameters

Headers

Sample Response Status Code: 200 Body: JSON Object

{

canSignUp: true,

message: "This user did not register for the lab"

}

Modify Attendee Settings

This endpoint can be used to extend an attendee’s lab environment before it expires. Also, if attendee wants to retake the lab one more time, maxTakeCount can be increased by setting it to larger value.

PUT {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees /{attendeeId}/settings

URI Parameter

Headers

Request Body (JSON)

Sample Response Status Code: 200 Body: JSON Object

{

maxDuration: 6H, maxTakeCount: 1,

remainingDuration: 2H30M

}

Delete deployment

If an attendee’s lab environment needs to be deleted, this endpoint can be used by specifying tenantId, labId and attendeeId.

DELETE {apiURL}/api/tenants/{tenantId}/labs/{labId}/attendees /{attendeeId}/deployment URI Parameter

Headers

Sample Response

Status Code: 204 No Content Body: Empty

Create Activation Codes

This endpoint can be used to add an activation code to a lab.

POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/activationcodes URI Parameters

Headers

Request Body (JSON)

Sample Response Status Code: 200 Body: JSON Object

{

"OperationType": null, "Status": "Success", "ErrorCode": null,

"ErrorMessage": null, "ErrorDetail": null, "Data": null,

"ErrorKey": null

}

Get Activation Codes

This endpoint returns all activation code in a lab.

GET {apiURL}/api/tenants/{tenantId}/labs/{labId}/activationcodes URI Parameter

Headers

Sample Response Status Code: 200

Body: JSON Object {

"OperationType": null, "Status": "Success", "ErrorCode": null,

"ErrorMessage": null, "ErrorDetail": null, "Data": [

"CL001", "CL002"

],

"ErrorKey": null

}

Schedule Start VM

POST {{apiURL}}/api/tenants/{{tenantId}}/labs/{{labId}}/schedule/startVM

This endpoint can be used to schedule the start of all VM instances present in active deployments. URI Parameters

Headers

Request Body (JSON)

{

"Timezone":"(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi", "ScheduledDate":"2024-05-10",

"ScheduledTime":1706, "ScheduleConfigId": 4

}

Sample Response Status Code: 200 Body: JSON Object

{

"OperationType": null, "Status": "Success", "ErrorCode": null,

"ErrorMessage": null, "ErrorDetail": null, "Data": null,

"ErrorKey": null

}

Schedule Stop VM

POST {{apiURL}}/api/tenants/{{tenantId}}/labs/{{labId}}/schedule/stopVM

This endpoint can be used to schedule the stop all VM instances present in active deployments. URI Parameters

Headers

Request Body (JSON)

{

"Timezone":"(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi", "ScheduledDate":"2024-05-10",

"ScheduledTime":1706, "ScheduleConfigId":5c

}

Sample Response Status Code: 200 Body: JSON Object

{

"OperationType": null, "Status": "Success", "ErrorCode": null,

"ErrorMessage": null, "ErrorDetail": null, "Data": null,

"ErrorKey": null

}

Clone Lab

Use this endpoint to clone an existing lab. Add the reference or base ODL labId as the “labId” URI parameter. POST {apiURL}/api/tenants/{tenantId}/labs/{labId}/clone

URI Parameters

Headers

Request Body (JSON)

Sample Response Status Code: 200

Body: JSON Object

{

"name": "Azure Functions & Logic App Serverless", "labId": "9a6c5f31-141a-4a19-921f-56ab091175ca"

}

The response object contains the ODL name and labId of the newly cloned ODL.

Exceptions

Sample Response

Status Code: 400/401/403/404/500 Body: JSON Object

{

"correlationId": 637105246526361093", "errorCode": "CL5014",

"errorMessage": " Voucher code expired",

"detailedErrorMessage": " Voucher code expired"

}

List of error codes will be available at https://bit.ly/2J7U70D .

Meta data – Attendee Status