Skip to content

Accessing Industrial IoT or external APIs during Local Development

This sections describes two options to access Industrial IoT APIs during local development and demonstrates how to configure the API development environment Postman for this purpose.

Applications must send their app credentials to the Token Management Service in order to request a token. For more information refer Application credentials.

Accessing Industrial IoT APIs using Application credentials

Application credentials are valid for 365 days. They can be used to create access tokens in Insights Hub without having to log into your tenant and capturing session cookies. However, access tokens generated using application credentials have admin scope, which means it is not suitable for testing applications with different user types. For more information refer Token Management Service, if necessary.

Prerequisites

  • Insights Hub user account on a developer environment.
  • The admin role for your Insights Hub environment mdsp:core:TenantAdmin

Create Application credentials

  1. Create your application credentials as described here.
  2. Encode the combination of the application credentials in Base64 format.

    • Combine credentials ID and password as shown below.

      {client_id}:{client_secret}
      
    • Encode the resulting string in Base64 format.

Generate the Access Token

  1. Send an HTTP request to the Technical Token Manager Service:

    POST /api/technicaltokenmanager/v3/oauth/token HTTP/1.1
    Host: gateway.{region}.{mindsphere.domain}
    X-SPACE-AUTH-KEY: Bearer {ServiceCredentialID: ServiceCredentialSecret as Base64 encoded string}
    Content-Type: application/json
    {
      "grant_type": "client_credentials",
      "appName": "application name",
      "appVersion": "version",
      "hostTenant": "TenantName",
      "userTenant": "Tenantname"
    }
    
  2. Extract the access token from the access_token field in the response and send it as Bearer token in the Authorization header of HTTP requests.

For more information refer Token Management Service.

Postman Example

The below postman collection should be imported in the postman. After successful import, you can replace the values in body, pre-request scripts, etc.

Postman
  {
    "info": {
      "_postman_id": "8b0ad76a-9f63-4946-9597-2443252645a0",
      "name": "Application Credential Token Generation with Example",
      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
      {
        "name": "Generate App Credential Bearer Token",
        "event": [
          {
            "listen": "prerequest", 
            "script": {
              "id": "7ed5b9aa-8e45-4d05-b1b4-6324300e6e8a",
              "exec": [
                "var id = '{Application Credential ID}';\r",
                "var secret = '{ Application Credential Secret}';\r",
                "pm.environment.set(\"base64token\", btoa(id + ':' + secret));"
              ],
              "type": "text/javascript"
            }
          },
            {
              "listen": "test",
              "script": {
                "id": "93b90d1f-2f5e-4487-a3f8-caac49b55cec",
                "exec": [
                  "var jsonData = pm.response.json();\r",
                  "pm.globals.set(\"BearerToken\", 'Bearer ' + jsonData.access_token);"
                ],
                "type": "text/javascript"
              }
            }
        ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-SPACE-AUTH-KEY",
                "value": "Bearer {{ base64token }}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\r\n\t\"grant_type\": \"client_credentials\",\r\n\t\"appName\":\t\"{Application Name}\",\r\n\t\"appVersion\": \"{Application Version }\",\r\n\t\"hostTenant\": \"{Host Tenant Name}\",\r\n\t\"userTenant\": \"{User Tenant Name}\"\r\n} "
            },
            "url": {
              "raw": "https://gateway.eu1.mindsphere.io/api/technicaltokenmanager/v3/oauth/token",
              "protocol": "https",
              "host": [
                "gateway",
                "eu1",
                "mindsphere",
                "io"
              ],
              "path": [
                "api",
                "technicaltokenmanager",
                "v3",
                "oauth",
                "token"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Get Tenant Users ( IAM )",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "{{ BearerToken }}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "https://gateway.eu1-int.mindsphere.io/api/im/v3/Users",
              "protocol": "https",
              "host": [
                "gateway",
                "eu1-int",
                "mindsphere",
                "io"
              ],
              "path": [
              "api",
              "im",
              "v3",
              "Users"
              ]
            },
            "description": "This API lists all the users of specific tenant"
          },
          "response": []
        }
    ],
    "protocolProfileBehavior": {}
  }

Accessing Industrial IoT APIs using Session Cookies

Session cookies are only valid for up to 12 hours and expire after 30 minutes of inactivity. However, by assigning your user specific application roles it is possible to test your application's behaviour for users other than admin.

Prerequisites

  • Insights Hub user account on a developer environment.
  • A Insights Hub developer role, either mdsp:core:Developer or mdsp:core:DeveloperAdmin.
  • A simple application to be registered at Insights Hub.

Deploy and Register the Application

  1. Deploy the application to Cloud Foundry and configure it in the Developer Cockpit as described here.
  2. Configure the application roles and scopes.

    Info

    Make sure to add the Core roles required to access the respective Industrial IoT APIs.

  3. Register the application.

  4. Assign an application role to your user.

Generate User Credentials

  1. Log into the application using a web browser.
  2. Open the developer tools your browser (press F12).
  3. Navigate into the cookies section.
    Chrome: Application > Cookies
    Firefox: Storage > Cookies.
  4. Copy the SESSION and XSRF-TOKEN cookies.

    Info

    These credentials will be valid for up to 12 hours and expire after 30 minutes of inactivity. Avoid timeouts by implementing a ping functionality into your application.

cURL Example

The following code block shows an example script for setting the user credentials in a cURL command - placeholders are indicated using angular brackets <>.

#!/bin/bash

TOKEN="<token-copied-from-browser>"
SESSION="<session-cookie-copied-from-browser>"

curl -vv \
  -G \
  --cookie "SESSION=${SESSION}; X-XSRF-TOKEN=${TOKEN}" \
  --data 'filter=dir*' \
  -X GET \
  https://<tenantId>-<appId>-<tenantId>.<regionId>.mindsphere.io/api/dataexchange/v3/directories/_PRIVATE_ROOT_ID

Postman Example

  1. Enter the HTTP request to be executed, follow the schema below:
https://{appName}.{region}.{mindsphere-domain}/{MindSphere-API}
https://my-app.eu1.mindsphere.io/api/iottimeseries/v3/assets

2.Click the Cookies link under the Send button.
3.Enter the application domain, e.g. my-tenant.eu1.mindsphere.io, and click on Add.
4.Add two cookies:

|    Key     |                                           Value                                           |
| ---------- | ----------------------------------------------------------------------------------------- |
| Cookie    | `SESSION=Y2YyYWJiM2YtYWMzZS00NjQyLWI1NTUtMGNhYWMxYzczOTJh; XSRF-TOKEN=d06e1798-51f1-4a1d-9484-46b28d23e11c; path=/; domain=.my-app.eu1.mindsphere.io;` |
| X-XSRF-TOKEN | `d06e1798-51f1-4a1d-9484-46b28d23e11c`       |

5.Send the HTTP request.

Accessing Industrial IoT /Token APIs

Prerequisites

The following are the prerequisites to use the Advanced Token Exchange (ATE) functionality (/token API):

  • the application that calls the 3rd party API must be enabled with custom application credentials
  • the application must be configured with UI to API mapping in Developer Cockpit

Procedure

After the above prerequisites are met, the first step is to get a token that enables to call the Advanced Token Exchange. This section describes the procedure to get a token.

  1. Send an HTTP request to the Technical Token Manager service to call ATE /token endpoint: To call the Technical Token Manager, an application credential issued on the developer or operator tenant is required. The token fetched using this endpoint will have the sufficient permissions for performing Advance Token Exchange. The upcoming JWT token should have the role "mdsp:core:ATE3rdPartyTechUser". This can be fetched as below. Encode the following combination of Client ID and Client Secret using Base64:

<client_id>:<client_secret>

Build the <X-SPACE-AUTH-KEY> using the word Basic, followed by a space and the encoded result. For example,

  X-SPACE-AUTH-KEY : Basic <ZGlvcDEtaGVybWlvbmUtaGVybWlvbmU6c2RqaGZhc2RqaGZqYXNkaGZqa2FzZGhmams=>
  POST /api/technicaltokenmanager/v3/oauth/token HTTP/1.1
  Host: gateway.{region}.{mindsphere.domain}
  X-SPACE-AUTH-KEY: Basic <ZGlvcDEtaGVybWlvbmUtaGVybWlvbmU6c2RqaGZhc2RqaGZqYXNkaGZqa2FzZGhmams=>
  Content-Type: application/json
  {
    "appName": "application_x",
    "appVersion": "1.0.0",
    "hostTenant": "host_tenant",
    "userTenant": "core"
  }

2.In order to access the ATE /token endpoint, extract the access token from the access_token field in the response from the above Technical Token Manager request and send it as Bearer token in the Authorization header of HTTP requests. The subject_token is provided through the technical token.

  POST /api/ate/v3/token HTTP/1.1
  Host: gateway.{region}.{mindsphere.domain}
  Authorization: Bearer <access_token>
  Content-Type: application/json
  {
    "subject_token": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbmZybGFiaC5waWFtLmV1MS1pbnQubWluZHNwaGVyZS5pby90b2tlbl9
    rZXlzIiwia2lkIjoia2V5LWlkLTYiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIwNTE4ZWYzZTNlZmY0ZWQ4YjdlMjlhMjEyMWJkODQ2MCIsInN1YiI6I
    m5mcmxhYmgtcGVyZmluLXYxIiwic2NvcGUiOlsicGVyZmluLmMiLCJtZHNwOmNvcmU6QVRFM3JkUGFydHlUZWNoVXNlciJdLCJjbGllbnRfaWQiOi
    JuZnJsYWJoLXBlcmZpbi12MSIsImNpZCI6Im5mcmxhYmgtcGVyZmluLXYxIiwiYXpwIjoibmZybGFiaC1wZXJmaW4tdjEiLCJncmFudF90eXBlIjo
    iY2xpZW50X2NyZWRlbnRpYWxzIiwicmV2X3NpZyI6IjliNTI0ZjE0IiwiaWF0IjoxNjEyMTcyNzYzLCJleHAiOjE2MTIxNzQ1NjMsImlzcyI6Imh0
    dHBzOi8vbmZybGFiaC5waWFtLmV1MS1pbnQubWluZHNwaGVyZS5pby9vYXV0aC90b2tlbiIsInppZCI6Im5mcmxhYmgiLCJhdWQiOlsibmZybGFia
    C1wZXJmaW4tdjEiLCJwZXJmaW4iXSwidGVuIjoibmZybGFiaCIsInNjaGVtYXMiOlsidXJuOnNpZW1lbnM6bWluZHNwaGVyZTppYW06djEiXSwiY2
    F0IjoiY2xpZW50LXRva2VuOnYxIn0.Ndo14t-XENpEKtfGJug2nNcHUiDMiPkI29ePazpbFfJO8wXs6sda00No3XhU42Ng8zzF9QM_kovVm1dfuR9
    QxLoBYhU6pVtUKV6trOZpCYGgXVG3OYJhORJBzuHnQ4uC5SRDAlVW1AUQ5_wjqRUFDHoe6433UiKSl0xnZjtGFHBphtV1Prfn0m9VXrNsF_Su_QEe
    YaTIWi3x6vrfptsHjoK0FYSuhGl9VTMINXixAN9iiCsZWeyK12D-z7TppSiXIQB-TfcKlLfcV_66tCMSqRXTtC4nkM8f5-rkHdeeCcUCBhdfaxqlA
    llNenZbx-xIlgZM1usQqLQx1ggNBuV6HA",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "resource": "https://gateway.eu1.mindsphere.io/api/<app_name>_<tenant_name>/<version>"
  }

With the authorization Token received in response, it is possible to access the endpoints of the API application hosted on another tenant. The API cannot access any Industrial IoT APIs.

Note

As a UI application developer, please note that you should not handover your UI application to the same tenant that is hosting the API that you externally depend on. This use case is currently not supported and your UI will not be able to reach the API.

Info

Token issued by ATE will expire in 30 minutes. Therefore, the consumer service is responsible for caching the token issued by the ATE. The token should be refreshed 5 minutes before token expires.


Last update: January 19, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.