Skip to content

Accessing MindSphere or external APIs during Local Development

This sections describes two options to access MindSphere 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 MindSphere APIs using Application credentials

Application credentials are valid for 365 days. They can be used to create access tokens in MindSphere 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

  • MindSphere user account on a developer tenant.
  • The admin role for your MindSphere tenant 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.

      1
      {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:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    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-requestscripts, etc.

Postman
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
  {
    "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 MindSphere 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 behavior for users other than admin.

Prerequisites

  • MindSphere user account on a developer tenant.
  • Cloud Foundry Command Line Interface (CF CLI)
  • A Cloud Foundry role which allows to push applications, e.g. SpaceDeveloper.
  • A MindSphere developer role, either mdsp:core:Developer or mdsp:core:DeveloperAdmin.
  • A simple application to be registered at MindSphere.

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 MindSphere 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 <>.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#!/bin/bash

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

curl -vv \
  -G \
  --cookie "SESSION=${SESSION};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:

    1
    https://{appName}.{region}.{mindsphere-domain}/{MindSphere-API}
    
    1
    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
    SESSION SESSION={session-cookie-copied-from-browser}; path=/; domain=.my-app.eu1.mindsphere.io;
    XSRF-TOKEN XSRF-TOKEN={token-copied-from-browser}; path=/; domain=.my-app.eu1.mindsphere.io;
  5. Send the HTTP request.

Accessing MindSphere /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 prerequistes 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,

1
  X-SPACE-AUTH-KEY : Basic <ZGlvcDEtaGVybWlvbmUtaGVybWlvbmU6c2RqaGZhc2RqaGZqYXNkaGZqa2FzZGhmams=>
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
  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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  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 MindSphere 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.

Any questions left?

Ask the community


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