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.

Accessing MindSphere APIs using Service Credentials

Service 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 service credentials have admin scope, which means it is not suitable for testing applications with different user types.

Prerequisites

  • MindSphere user account on a developer tenant.
  • The admin role for your MindSphere tenant mdsp:core:TenantAdmin

Create Service Credentials

  1. Create your service credentials as described here.
  2. Encode the combination of the service credentials in Base64 format.

    • Combine credentials ID and password as shown below.

      1
      {credentials_id}:{password}
      
    • Encode the resulting string in Base64 format.

Generate the Access Token

  1. Send an HTTP request to the OAuth Authorization Service:

    1
    2
    3
    4
    POST {tenantName}.piam.{region}.{mindsphere-domain}/oauth/token
    Accept: */*
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic {credentials-in-Base64-format}
    
  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.

Postman Example

  1. Create a test script that stores the access token in a global variable:

    • Set the HTTP request.

      1
      POST {tenantName}.piam.{region}.{mindsphere-domain}/oauth/token
      
      1
      POST my-tenant.piam.eu1.mindsphere.io/oauth/token
      
    • Define the following headers:

      Key Value
      Accept */*
      Content-Type application/x-www-form-urlencoded
      Authorization Basic {credentials-in-Base64-format}

      Header Parameters

    • Write the script.

      1
      pm.globals.set("{variable-name}", pm.response.json().access_token );
      
      1
      pm.globals.set("token", pm.response.json().access_token );
      

      Script

  2. Download the specification of the API you want to access from developer.mindsphere.io.

  3. Copy the content of the YAML file.
  4. In Postman, select Import and Paste Raw Text.
  5. Paste the content of the YAML file into the editor and add the following line:

    1
    host: gateway.{region}.mindsphere.io
    
  6. Click Import.

  7. Right-click on the new collection and select Edit.
  8. Select the Authorization tab.
  9. Select the authorization type Bearer.
  10. Enter the global variable name in the Token field and click Update.
  11. Run the script you created in step 1. This issues an access token and stores it in the global variable. It is automatically used for authorization in HTTP requests to the previously configured API.

    Authorization

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.