Containers
Workspaces - How to embed

Important: To successfully complete this tutorial, you need to have an active Sphere Engine account with a dedicated API endpoint and API token. Register for a Sphere Engine account by filling in the sign-up form. Create your Sphere Engine account here.

This tutorial will show you how to start using workspaces.

The diagram below illustrates how the starting workspace flow works. It is divided into two stages. First, you have to create a workspace using our API. Next, you must pass the workspace data into a JavaScript snippet that renders the workspace in your application.

Your UserYour ApplicationSphere Engine ContainersEnterPOST /api/v1/workspacesJSON with Workspace IDWebsite with JS SnippetYour UserYour ApplicationSphere Engine Containers
Fig. 1. Workspace flow diagram

Step 1: Logging in to the panel

After creating your account and successfully logging in, you will be redirected to the client's dashboard.

Step 2: Select a project from list

Select the Project ID of the first project from the Projects list.

Step 3: Copy access token

To call any API method, you need to be authenticated with an access_token that you can generate in the token manager section of the Sphere Engine client panel.

Step 4: Start a workspace using API

The following example shows how to call the API method responsible for creating a new workspace using the curl command. Now, we can call the API method in the following way:

curl -X POST \
  -F "project_id=__PUT_HERE_PROJECT_ID__" \
  "https://<customer_id>.containers.sphere-engine.com/api/v1/workspaces?access_token=<access_token>"

The response from the API call will be a objects which represents a starting workspace, for example:

{
  "message": "Workspace has been created",
  "workspace": {
    "id": "48dba362e85e4aebac3dc8e6b0677ff7",
    "project": {
      "id": "eef024c1d14f46319517a65edafb5ee3",
      "name": "EXAMPLE"
    },
    "created_at": "2021-01-01 10:20:37 +0000",
    "terminated_at": null,
    "last_usage": null,
    "inactivity_timeout": 15,
    "workspace_token": "73543c2d-3476-46ee-a49c-227f59181961",
    "workspace_token_required": true,
    "state": {
      "code": 1,
      "name": "starting",
      "error_reason": null
    },
    "auto_resume": true,
    "workspace_init_failed": false,
    "streams": {
        "workspace_init_output": null,
        "workspace_init_error": null
    },
    "retention_time_stopped": 0,
    "retention_time_total": 0,
    "permissions": {
        "enter": true,
        "remove": false,
        "stop": false
    },
    "config": "{content of the configuration}",
    "workspace_url": "https://<endpoint>/workspace/48dba362e85e4aebac3dc8e6b0677ff7"
  }
}

Step 5: Embed a workspace in your application

The code responsible for workspace initialization should be inserted only once, immediately after the <body> element.

<script>(function(d, s, id){
  SE_BASE = "<customer_id>.containers.sphere-engine.com";
  SE_HTTPS = true;
  SE = window.SE || (window.SE = []);
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return;
  js = d.createElement(s); js.id = id;
  js.src = (SE_HTTPS ? "https" : "http") + "://" + SE_BASE + "/static/sdk/sdk.min.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "sphere-engine-jssdk"));

SE.ready = function(f) {
  if (document.readyState != "loading" && document.readyState != "interactive") f();
  else window.addEventListener("load", f);
};
</script>

The following code should be inserted on the page in the spot where you want the workspace to be displayed:

<div class="se-workspace" data-workspace="__PUT_HERE_WORKSPACE_ID_FROM_JSON_RESPONSE__"></div>
  Contents