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 for technical users such as applications. 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 shows you how to generate a token using app credentials.

Call the following endpoint: https://{tenantName}.piam.{region}.{mindsphere-domain}/oauth/token with the following header and body (grant_type=client_credentials):

1
2
3
4
5
6
POST /oauth/token HTTP/1.1
Host: {tenantName}.piam.{region}.{mindsphere-domain}
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://{tenantName}.piam.{region}.{mindsphere-domain}/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.

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.

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://{tenantName}.piam.{region}.{mindsphere-domain}/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.{region}.{mindsphere-domain}/api/identitymanagement/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.