Containers
Workspaces - security

Workspaces in the Sphere Engine Containers module provide mechanisms for secure integration. The workspace_token parameter protects the workspace from unauthorized use.

Workspace token

In a production environment, we recommend using the workspace_token that fully protects the widget from unauthorized use. It should be enabled in the API call which creates the workspace.

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

Attaching a workspace token

Workspace token should be attached to the embedded workspace in the form of the appropriate HTML attributes with the data- prefix, namely data-workspace-token for the workspace-token parameter.

An example of HTML code used to embed a widget prepared to support the signature:

<div data-id="example-workspace" 
    data-workspace="__PUT_HERE_WORKSPACE_ID_FROM_JSON_RESPONSE__"
    data-workspace-token="__PUT_HERE_WORKSPACE_TOKEN_FROM_JSON_RESPONSE__">
</div>

Checking the source

Using a list of defined web addresses on which a workspace can be embedded as a security measure minimizes the risk of unauthorized use of the workspace. It is a method that's the simplest and the fastest to configure. It doesn't require any additional mechanisms.

You can define the list of allowed addresses on the Menu > Containers > Projects > CORS settings page in the Sphere Engine Client Panel. You can specify one or multiple addresses, for example:

http://yoursite.com
https://yoursite.com

The Sphere Engine system verifies HTTP requests from end-users using the client's system (i.e., the page where the workspace is embedded). Only requests directed to addresses in the list of defined addresses are accepted.