Skip to content

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

Any questions left?

Ask the community


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