Skip to content

Accessing MindSphere APIs from Applications outside MindSphere

This section describes how self-hosted applications can access MindSphere APIs without being integrated into MindSphere. This way you can utilize MindSphere services to enrich your own applications.

Info

Self-hosted applications can instead be integrated into MindSphere.

Prerequisites

For this Getting Started you need:

  • MindAccess DevOps Plan - this is your MindSphere account (tenant).
  • Outbound Traffic Upgrade - this includes a data volume for consuming MindSphere services from outside of the MindSphere platform. To get this upgrade, your tenant admin needs to contact their assigned Account Executive or Customer Success Manager.
  • mdsp:core:TenantAdmin role

Note

Application Credentials are only required as technical users for an application. Applications can access other tenants' data using the Token Management Service, if necessary.

Application Credentials

Applications must send their app credentials to the Token Management Service in order to request a token. App credentials consist of a client ID and a client secret. They are created after uploading an application to the Developer Cockpit or Operator Cockpit and must be provided as environment variables of the application.
Access for an application must be issued manually in the "Authorization Management" in order to create app credentials. For Cloud Foundry applications, the Operator Cockpit automatically provides the app credentials as environment variables of the application.

For more information on fetching the app credentials from Operator Cockpit refer App credentials.

App credentials are version specific and must be updated, if a new version of an application is uploaded. This also means that the app credentials issued in Developer Cockpit are not valid anymore, once the application has been transferred to the operator tenant.

In order to revoke the credentials, de-register the application.

App credentials expire after a maximum of 365 days. Once the App credentials completes 365 days, rotate the application credentials. For more information refer Rotate Application credentials.

Attention

  • App credentials are created per account. If you follow the DevOps Application Lifecycle, you need one set of application credentials for your Dev account and another for your Ops account.
  • App credentials cannot be used by mobile apps. Refer How To for integrating MindSphere applications into native mobile apps.
  • It is required to only use one set of app credentials per application instance. This ensures that only one part of your system is affected, if the credentials are compromised.

Generating a Token

This section describes how to use app credentials to generate bearer token using 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 {ApplicationCredentialID: ApplicationCredentialSecret as Base64 encoded string}
Content-Type: application/json
{
  "grant_type": "client_credentials",
  "appName": "application name",
  "appVersion": "version",
  "hostTenant": "TenantName",
  "userTenant": "Tenantname"
}

To get the token, retrieve the content of access_token from the 200 success response.

The following example shows how to request an access_token using curl and jq:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST 'https://gateway.{region}.{mindsphere.domain}/api/technicaltokenmanager/v3/oauth/token' \
-H 'X-SPACE-AUTH-KEY: Bearer $(echo -n {AppCredentialID}:{AppCredentialSecret} | base64)' \
-H 'Content-Type: application/json' \
-d '{
      "grant_type": "client_credentials",
      "appName": "application name",
      "appVersion": "version",
      "hostTenant": "TenantName",
      "userTenant": "Tenantname"
}'

Postman Example

The below postman collection should be imported in the postman. After successful import, you can replace the values.

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.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": {}
  }

Info

The issued token is valid for 30 minutes. You have to request a new token after the 30 minutes have expired.

For more information on Token management refer Token Management service.

Calling MindSphere Endpoints

Create another request to an API endpoint with the following header keys:

1
2
Authorization: Bearer {token}
Content-Type: application/x-www-form-urlencoded

The following example shows how to request a list of all users of your account from the Identity Management API. Note that in this example the region is specified as eu1.

1
2
3
GET /api/identitymanagement/v3/Users HTTP/1.1
Host: gateway.eu1.mindsphere.io
Authorization: Bearer {token}

Info

You will only receive a success response, if you pass a valid token to Bearer {token}. In the same way you can use all MindpShere APIs.

Code Example (Python3)

We use Python3 and the requests_oauthlib to connect to the MindSphere IAM API.

In this example you get a token from the IAM service and use it to fetch all users and print those with the role mdsp:core:StandardUser. Replace the placeholders {tenantName} and {region} in the code below with your tenant name and region.

 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
import base64
import requests

URL = "https://gateway.{{region}}.{{mindsphere_domain}}";
TOKEN_ENDPOINT = '/api/technicaltokenmanager/v3/oauth/token'
IAM_ENDPOINT = '/api/im/v3/Users'

#Replace values for appName, appVersion, hostTenant, userTenant
payload = "{\"grant_type\": \"client_credentials\",\"appName\":\"appName\",\"appVersion\": \"version\",\"hostTenant\": \"tenantName\",\"userTenant\": \"tenantName\"}"

# Encoding of App Credentials in Base64 format
encoded = base64.b64encode(b'mendix01-mendix-asdf:RnBnpdDyOfTiiAgVf8Yk6f9Jc6jta8l1Wru9XNzrK3a').decode()
headers = {
  'X-SPACE-AUTH-KEY': 'Bearer ' + encoded,
  'Content-Type': 'application/json'
}

token_res = requests.post(url = URL+TOKEN_ENDPOINT, headers = headers, data = payload)
data = token_res.json()

#Token Generated using App Credentials
token = data['access_token']

print(data)

auth_headers = {
  'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json'
}

# sending get request and saving the response as response object
iam_response = requests.get(url = URL+IAM_ENDPOINT, headers = auth_headers)

# extracting users data in json format
users = iam_response.json()

#Users List
print(users)

Any questions left?

Ask the community


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