Skip to content

How to use SAS tokens

In some scenarios it could be relevant to call MIKE Cloud Platform services directly instead of via Metadata service. In the following case standard authentication procedures apply for retrieval of the SAS token which later can be used calling relevant services directly. First, determine the direct service base URI. Then, get a Shared Access Signature Token (SAS Token) from the root api host and use it for requests to the direct service.

To find out the base URI for a service use the following end point:

GET/api/services/{serviceName}/baseuri api-version 3

Example response could look something like below.

{
    "data": "https://<seviceName>-mike-platform-dev.eu.mike-cloud-dev.com/api/"
}
Do not try to modify or read information from the returned base uri. The structure and content of service URIs are driven by internal rules of the Platform and can change at any time.

There serviceName is service id which can be retrieved using the following endpoint:

GET/api/services/ids api-version 1

Example response could look something like below.

[
    "md",
    "engine",
    "timeseries",
    "gis",
    "coordinatesystems",
    "raw",
    "sharing"
]

What is SAS token

  • SAS token is authorization token (represented by url-friendly string) that can be issued for a specific project, or a dataset within a project, or a subtree of folders under a given project.
  • The SAS token contains information about the customer and user who issued it, an expiration date, resource identification (project/dataset), and set of privileges that the issuer has with respect to the resource (at the time of creation).
  • The inner services (such as Multidimensional service, Timeseries storage etc.) can accept this token, and validate that the caller can access the requested resource. And the token is the only authentication/authorization method used in the call - with the token no AD registration is necessary to exist for the caller.
  • In some cases even the Metadata service itself can accept a SAS token to perform certain operations (e.g. file upload).

SAS token retrieval

The following endpoints are exposed by the Metadata service to get the SAS token:

GET/api/security/sastoken?projectId=<projectId>&resourceId=<datasetId> - api-version 2 generates a token for the given project (and optionally a dataset)

GET/api/security/recursivesastoken?projectId=<projectId>&expiration=<datetime> - api-version 2 generates a recursive token for the given project (with optional expiration specification). The recursive token contains privileges that can be applied to ALL subprojects of the given projects. I.e. in order for the token to be useful, the caller should have at least a READ privilege in all subfolders of the given folder.

SAS token use

To stich all the above let's take an example where we try to run engine execution using SAS token. In the following example we would first send a request to Metadata service to retrieve base URI for engine execution.

Click to show example shell script to retrieve engine service base URI

projectId="<replacewithprojectid>"
openapikey="<replacewithopenapikey>"

# create execution
curl -L -X GET "https://api.mike-cloud-test.com/services/engine/baseuri" \
  -H 'api-version: 1' \
  -H "dhi-open-api-key: $openapikey" \
  -H 'Content-Type: application/json' \

Next we should call Metadata service to retrieve valid SAS token. It returns the SAS token in the following response:

{
  "data": <sas token as string>
}

It is strongly recommended not to modify or even get information from the SAS token. The structure and content of the SAS token is driven by internal rules of the Platform and it is not versioned. Therefore, any logic based on the internal structure of the SAS token could break over time.

Click to show example shell script to retrieve SAS token

projectId="<replacewithprojectid>"
openapikey="<replacewithopenapikey>"

# create execution
curl -L -X GET "https://api.mike-cloud-test.com/api/security/sastoken?projectId=<projectId>" \
  -H 'api-version: 2' \
  -H "dhi-open-api-key: $openapikey" \
  -H 'Content-Type: application/json' \

Next we should use the generated SAS token and retrieved service URI calling engine service directly.

Click to show example shell script to start an engine execution using SAS token

projectId="<replacewithprojectid>"
sasToken="<replacewithgeneratedsastoken>"
baseUri="<replacewithretrievedbaseuri>"

# create execution
curl -L -X POST "https://api.mike-cloud-test.com/api/compute/execution" \
  -H 'api-version: 2' \
  -H "dhi-sas-token: $sasToken" \
  -H 'Content-Type: application/json' \
  --data-raw '{
      "inputs": [
        {
          "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
          "engine": "FemEngineHD"
        },
        {
          "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
        }
      ],
      "options": {
        "poolType": "VM-S-5",
        "nodeCount": 1
      }
    }'