Skip to content

Self-Hosted Application – Access MindSphere APIs

In this section you will learn how to use MindSphere APIs from an application hosted outside of MindSphere platform (self-hosted). This way you can utilize MindSphere services to enrich your own applications.

This Getting Started includes a step by step guide, which leads you through the basic setup.

Prerequisites

For this Getting Started you need:

  • MindAccess DevOps Plan - this is your MindSphere account (tenant)
  • mdsp:core:TenantAdmin role
  • Outbound Traffic Upgrade - this includes a data volume for consuming MindSphere services from outside of the MindSphere platform.

Attention

Because of the nature of this scenario and its increased amount of outbound traffic, you may be required to increase your Outbound Traffic limit in the future.

Creating Service Credentials

In order to create new or update existing service credentials, you have to make a service request. Contact the GTAC (Global Technical Access Center) or fill out the MindSphere Support form accessible from your MindSphere Launchpad using the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Subject: Request for [new| updated] Service Credentials for self-hosted application

Dear MindSphere Support,

Please [create new| update existing] Service Credentials for the tenant with the following parameters:

Tenant name: {yourTenant}
Account type: {Developer (Dev) or Operator (Ops) depending on your account type}
Service Credentials ID: {name for the service credentials set}
Include subtenant impersonation: {yes/no. Whether to include the capability to request tokens that are restricted to a specific subtenant}

Note

If you make the request via the MindSphere Support form on your MindSphere Launchpad, you do not need to include the tenant name and the Soldto. Also, remove any special characters from the template above.

If you make the request via GTAC, find your Soldto and the tenant name are on the Welcome Letter that the tenant admin has received.

After verification, you receive your requested service credentials in a secure manner.

Attention

The service credentials are created per account. If you follow our DevOps Application Lifecycle, you need one set of service credentials in your Dev account and one set of service credentials in your Ops account.

Attention

It is required to use a single set of service credentials for one application instance only. This ensures that only one part of your system is affected, if the credentials are compromised.

Generating a Token

This section shows you how to generate a token using service credentials.

Call following endpoint: https://{yourTenant}.piam.eu1.mindsphere.io/oauth/token with following header and body ("grant_type=client_credentials"):

1
2
3
4
5
6
POST /oauth/token HTTP/1.1
Host: {yourTenant}.piam.eu1.mindsphere.io
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {ServiceCredentialID: ServiceCredentialSecret as Base64 encoded string}

grant_type=client_credentials

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
curl -s \
  -H "Authorization: Basic $(echo -n {ServiceCredentialID}:{ServiceCredentialSecret} | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -X POST https://{yourTenant}.piam.eu1.mindsphere.io/oauth/token | jq -r .access_token

Info

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

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

Example:

This example shows how to request a list of all users of your account from the Identity Management API.

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.

Info

You need to install the dependencies via the following command:

1
pip install requests requests_oauthlib
 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
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

# add your account name here
refresh_url = 'https://{yourTenant}.piam.eu1.mindsphere.io/oauth/token'

# enter your service user credentials here
credentials = {
    'client_id': '{ServiceCredentialID}',
    'client_secret': r'{ServiceCredentialSecret}',
}

# create a backend client and retrieve a token
oauthclient = BackendApplicationClient(client_id=credentials['client_id'])
oauthsession = OAuth2Session(client=oauthclient)
token = oauthsession.fetch_token(token_url=refresh_url, client_id=credentials['client_id'],
        client_secret=credentials['client_secret'])

# create session with token
client = OAuth2Session(client_id=credentials['client_id'], token=token)

# get a list of all users of your tenant
r = client.get('https://gateway.eu1.mindsphere.io/api/im/v3/Users')

# List users with mdsp:core:StandardUser role
users = r.json()['resources']
for user in users:
    roles = user['groups']
    for role in roles:
        if role['display'] == 'mdsp:core:StandardUser':
            print(user['userName'])

Any questions left?

Ask the community


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