Developer Guide

Bosch IoT Permissions - also known as Identity Management, or IM3 - is a fully-managed cloud service to administrate your users, groups, roles, permissions and tenants. The service provides RESTful APIs, an administrative user interface, user-self-service interfaces and Java client libraries.

Introduction

The main scope of Bosch IoT Permissions is to manage the permissions to read, write, or execute operations in an IoT application. Thanks to this fully managed cloud service, users can be organized into groups according to the current structure of a company. This supports a flexible and scalable business organization that can be restructured without the need to involve the IT specialists.

The user permissions are derived from their roles and the group membership. The decisions to give a user access to certain functions are based on the roles that individual users perform as a part of an organization. The access management model facilitates comprehensive access control policies. For that, hierarchical groups, default roles, and custom role definitions are provided. This reduces the source of administrative errors and consequently the costs for secure user administration.

The service provides a RESTful HTTP API, an administrative user interface, user-self-service interfaces and Java client libraries.

About this Guide

This document is intended to help software developers understand how to use the Bosch IoT Permissions service in order to provide user and permission administration within their application.

This document assumes that you are versed in using Java and a Java-based IDE and familiar with the basic concepts of databases, object-oriented programming, and Web technologies.

Building Blocks 

The Identity Management component consists of various layers. The public layer exposes interfaces which can be used by your business application over the Bosch IoT Permissions Service APIs. The implementation details are hidden using private layers.

Following figure shows the schematic setup of a business application using the Bosch IoT Permissions service APIs.

Service Endpoints

After proceeding as described at Subscribe via Bosch IoT Marketplace, Bosch IoT Permissions provides the following endpoints:

API Endpoints

Service API 1 endpoint: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest
For XSD schemas see https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/schema.html

Service API 2 endpoint:  https://permissions-api.s-apps.de1.bosch-iot-cloud.com/2/rest 

JavaScript-Support-API endpoint: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/js/1/rest

Service UI

Service UI: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/

Please use the "Manage" link of your service instance in Cloud Foundry.
In case you use the link above for a login you will need to provide your tenant name, username, and password.

After logging in the landing page will give you access to different views, e.g.:

  • Client Access Tokens,
  • API Keys,
  • Admin UI,
  • your User Profile.

Depending on your permissions, you might not see all of these.

All user interfaces are described in detail at Service UIs.

Getting started - Bosch IoT Suite

Bosch IoT Permissions is provided as a service in the Bosch IoT Suite portal. This section describes how to get your own Bosch IoT Permissions service instance and how to start using it.

Subscribe via Bosch IoT Suite

To place your subscription via the Bosch IoT Suite portal please proceed as follows:

Starting point is https://bosch-iot-suite.com/

  1. Click My account and Sign in with your Bosch ID.
    In case you have no Bosch ID yet, feel free to register a new user account.
    Once the authentication is successful, you will be re-directed to the Bosch IoT Suite portal.

  2. Click New Subscription and select Bosch IoT Permissions.

    1. Select the service plan
      Currently the Free plan is the only option offered with this channel.

    2. Set the name of your instance
      You can book multiple instances of each type of service so make sure you set a speaking name.

    3. Click Subscribe

    4. The Status will be "Provisioning" while the service subscription mechanism checks the validity, e.g. if the instance name is unique.

    5. In case the Status is still not "Active" after some seconds, click the Refresh button.

  3. Check your Credentials
    Tip: The Client Access Token will be required for each and every request at the Bosch IoT Permissions APIs.
    This is composed of the "imClientId" and the "imClientSecret" which you can find in this view.

  4. To Edit the service configuration, click the respective action button.

  5. The Dashboard will be your main entry point to use the service


Start working with the Dashboard

Given you are still at the Bosch IoT Suite subscription page, the easiest way to explore the Bosch IoT Permissions administrative user interface is to follow the "Dashboard" link of your instance.

The link opens the Admin UI, where you can see the data of one tenant. All user, groups, roles, etc. which you will create henceforth will belong to this tenant.

The Bosch ID which you have used to log in at the Bosch IoT Suite subscription page has also been used by our service to create you an initial user empowered to do all administrative tasks.

If you need to log in at a later point in time with your Bosch ID, you will need to select the option "Sign in with Bosch".

However, for development feel free to create user entities directly at Bosch IoT Permissions and to log in with username and password instead.

Basic Entities

The following figure introduces the basic entities managed within Bosch IoT Permissions.

Further details at Concepts > Basic Entities

Default Roles and Permissions of your Admin user

The initial user gets IM Service Administrator - Role (i.e. he is the very first admin for your new tenant).

Find details at following pages:

Get familiar with the Admin UI

For the beginning you can try to create a new "role" and make it available for all (upcoming) users of your tenant.

All steps can be found at Service UIs > Administrator UI >... > Create Role and Create a Group-Role assignment.

Example:

Later, you might want to programmatically register your application to be visible at this UI and to empower other user to access it.

Start working with the REST API

User authentication and authorization is one of the main prerequisites in order to use Web applications.

Bosch IoT Permissions provides various authentication and authorization methods:

Service API 2

  • JSON Web Token - JWT
  • Basic Authentication
    You provide a username and a password to a tenant specific authentication resource. Upon success Bosch IoT Permissions creates an ID Token.
    The issued ID Token does not provide any authorization information. It merely defines that the user is authenticated.
  • Bearer Authentication
    You provide an ID Token to a tenant specific authorization resource. Upon success Bosch IoT Permissions creates an Authorization Token.
    The issued Authorization Token provides the roles and permissions your IoT application will check for. A Bearer authentication is also used when changing the initial password of a user.
  • Agent Credentials
    While creating Agent Credentials (e.g. for an Application which needs to self-install into Bosch IoT Permissions) the user defines a sub-set of his roles and permissions.

Service API 1

  • All resources of Service API 1 accept Authorization Tokens
  • CRUD operations for all basic entities (User, Group, Role, Permission)

  • CRUD operations for tenant relations entities (Offering, other Tenants, Relations)

Service API  documentation with try-out functionality


Client Access Token

The Client Access Token is required for each API call.

Your Client Access Token is composed as follows 

clientId:clientSecret

These values should be retrieved as a result of a successful subscription.

By adding this header to your request, we will know that your solution (application) is bound to a valid Bosch IoT Permissions subscription.

Additionally to this Authorization, most of our resources are protected and will require a valid ID Token or Authorization Token for the user.

Register an Application

In our example, we will register a solution (application) and make its application roles and permissions available for other APIs or users via the Bosch IoT Permissions service.

To register a solution, you will need a user who is empowered with the INSTALL_APPLICATION permission.

  1. Authenticate to get an ID Token
    1. POST /authentication/{user-tenant)

    2. Use the Basic Auth header containing the credentials.
      Example: Basic username:password
      The username:password must be Base64 encoded.

    3. Upon success, Bosch IoT Permissions issues an ID Token.

    4. Copy the ID Token to your clipboard, as you will need to enter it in an input field for the next request.
  2. Use the ID Token to retrieve an Authorization Token
    1. POST /authorization/{user-tenant-id}

      1. Use the Bearer header containing the ID Token from step 1.
        Example: Bearer xxxIDxTokenxxx
        The ID Token must be Base64 encoded.

      2. The user-tid is your tenant ID .
      3. Application is IM - Acronym for Identity Management.
      4. Scope is pn - Acronym for permission names.
    2. Upon success, Bosch IoT Permissions issues an Authorization Token.

    3. Copy the Authorization Token to your clipboard, as you will need to enter it in an input field for the next request.
  3. Use the Authorization Token to register a new application
    1. PUT/applications/{app-name}
    2. Use the Bearer header containing the Authorization Token from step 2.
    3. Set an own app-name, as the name must be unique. (Our example uses my-new-app.)
    4. The body contains one role (we name it my-new-role) which holds one permission (we name it my-new-perm01), and a second permission "my-new-perm02" without any role.
      Feel free to use real roles and permissions as soon as you know which ones will be useful for you new app.


      {
          "initial_setup": {
              "permissions": [{
                      "name": "my-new-perm01"
                  },
                  {
                      "name": "my-new-perm02"
                  }
              ],
              "roles": [{
                  "name": "my-new-role",
                  "permission_names": [{
                      "application_name": "my-new-app",
                      "permission_name": "my-new-perm01"
                  }]
              }],
              "version": "0.1.0"
          }
      }

    5. Upon success, Bosch IoT Permissions registers the new application for your tenant.

Check your Work at the UI

Navigate to your Dashboard and open then Role Management section.

In case your application was registered successfully, the Applications column should display your new app.

  • Pin my-new-app, and its role as well as both permissions get highlighted.
  • Pin my-new-role, and it's my-new-perm01 gets highlighted.
  • Pin my-new-perm02, and the role should not be highlighted any longer.
    However if you want to make this permission also available for users or groups, feel free to create an assignment with your first tenant role.
    In the User Management view you can than add it to the "all users" group.

For any help you might need in the further course of the service usage, feel encouraged to consult the complete developer guide.


Getting started - Bosch IoT Cloud

Bosch IoT Permissions is provided as a service in the Bosch IoT Cloud marketplace. This section describes how to get your own Bosch IoT Permissions service instance and how to start using it.

Subscribe via Bosch IoT Marketplace

You have two possibilities to subscribe to the Bosch IoT Permissions service (also known as Identity Management, or IM3):

  • Use the Cloud Foundry command line tool
  • Use the Web UI of the Bosch IoT Cloud Services Marketplace

In this example you will use the Cloud Foundry command line tool "cf".

Preconditions

You may need to install "cf" first. Please refer to the Cloud Foundry documentation "Installing the cf Command Line Interface" in this case.

Procedure description

Use the Cloud Foundry command line tool and proceed as follows:

  1. Log in to the Cloud Foundry infrastructure and select the space where your application is running.
    Please refer to section "Login" in the Cloud Foundry documentation > Getting Started with the cf CLI for more information on this step.
  2. Use the following command to see which services are available:

    cf marketplace

    The result should contain the IM3 service and the service plans:

    im3-service   Free, Starter*, Standard*   User management, role-based access control and 
       multitenancy for IoT applications.
  3. Use the following command to create a service instance with service parameters:

    cf create-service im3-service Free my-permissions -c params.json

    Where:

    • im3-service - is the service ID of the Bosch IoT Permissions service (i.e. our offer in the Cloud Foundry).

    • Free - is the service plan name. You may choose one of the other available plans.
    • my-permissions - is the name you can choose for your service instance

    The service parameters can be provided by means of the specified file params.json which must have the following content:

    {
    	"tenantName": "MY_TENANT",
    	"adminName": "myAdmin",
    	"adminPassword": "TopSecret1!",
    	"adminEmail": "myadmin@example.com"
    }

    Providing service parameters with -c params.json is optional and could also be omitted.

      • tenantName - The tenant name must be a unique name with a length between 2 and 24 characters. It is allowed to contain uppercase letters (A-Z), the underscore character (_) and numbers (0-9). When omitted a unique name is generated.
      • adminName - The name of the initial administrative user. When omitted the default name is "Admin" is used.
      • adminPassword - The password of the initial administrative user. When omitted the default password is "ChangeThis1!" is used and this default password must be changed on first login. 
      • adminEmail - The email address of the initial administrative user. If omitted, no email address will be set. Providing an email is recommended, as this allows to reset the password via email.

    Alternatively the service parameters can be provided inline using the following format:

    cf create-service im3-service Free my-im3 -c "{\"tenantName\":\"MY_TENANT\",\"adminNam
    e\":\"myAdmin\",\"adminPassword\":\"TopSecret1!\",\"adminEmail\":\"myadmin@example.com\"}"

    With the parameters above an initial user is specified which is created within Bosch IoT Permissions. If you have a Bosch ID user, you can use this one alternatively as initial tenant administrator (see Specify a Bosch ID as initial administrator).

  4. Display the service metadata with the following command

    cf service my-permissions

    The result should look similar to the following one:

    Service instance: my-permissions
    Service: im3-service
    Tags:
    Plan: Free
    Description: User management, role-based access control and multitenancy for IoT applications.
    Documentation url: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/app/im-docu-spec
    Dashboard: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/?imtid=<YOUR-TENANT-ID>

    While:

    • Dashboard - provides the URL which you can use to log into the Admin UI

Results

  • You have created your own service instance.
  • You have an initial administrative user with Initial admin user roles available.
  • You have the Dashboard URL available to log into the Admin UI with the administrative user.

If you did not specify a password via service parameters, we strongly recommend to change your initial password "ChangeThis1!" to a secret one.

You now may proceed with one of the following:


Specify a Bosch ID as initial administrator

Subscribe via Bosch IoT Marketplace describes how to subscribe to the Bosch IoT Permissions service (also known as Identity Management, or IM3) in order to get a tenant and an initial administrative user.

In step 3 an initial user is specified which is created within Bosch IoT Permissions.

Alternatively, to empower a user with a Bosch ID as the tenant administrator please use following parameters:

{
	"sub": "134323523426"
	"email": "my-email@example.com"
}

Where:

    • sub - The subject ID (i.e. the Bosch ID of the user who should get tenant administrator rights).

    • email - The email address associated to the respective Bosch ID.

Initial admin user roles

After booking Bosch IoT Permissions (also known as Identity Management, or IM3) from the Marketplace, your new tenant with an initial admin user is created.

The newly created tenant gets roles and permissions from IM automatically via Offering.


The initial user gets IM Service Administrator - Role (i.e. he is the very first admin for your new tenant).

Find details at following pages:

Change the initial password of your initial user

This page describes how to change the initial password of your initial administrative user.

Preconditions

  • You have your own service instance available.
  • You have an initial administrative user with username "Admin" and password "ChangeThis1!".
  • You have the Dashboard URL available to log into the Administrator UI with your initial user.

Procedure description

  1. Get the Dashboard URL of your service instance.
    You can use the following command, if your named your service instance "my-permissions":

    cf service my-permissions

    The result looks like this:

    Service instance: my-permissions
    ...
    Dashboard:  https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/?imtid=<YOUR_TENANT_ID>
    ...
  2. Open the Dashboard URL in your browser.

  3. Click on "Login" and enter your administrative user's initial credentials

  4. The change password dialog appears.
    Provide your old password "ChangeThis1!", then type and re-type the new password.
  5. Confirm your changes with the Change password button. If the change is successful, the Administrator UI will be loaded.

Results

You have changed the administrative user's password. Now you can start to use the Administrator UI. See Administrator UI.

Push a trivial application to which you can bind

If you don't have your own application yet, you can push any trivial application to Cloud Foundry.

This example shows how to create an app based on the Cloud Foundry Staticfile Buildpack. The app does nothing, but it can be used to bind it to your service.
With such a binding you will get the Bosch IoT Permissions API endpoint URL, as well as credentials for using the API.

Preconditions

  • Cloud Foundry command line tool "cf" is installed
  • You have subscribed to the Bosch IoT Permissions service (see Subscribe via Bosch IoT Marketplace).
    Our example assumes you have used my-permissions as service instance name.

Procedure description

  1. Create an empty directory.

  2. Go into this directory and create an empty file named "Staticfile".

  3. Push this file to Cloud Foundry.
    The Cloud Foundry Staticfile Buildpack will be detected automatically, due to the file named "Staticfile".

    cf push my-app -m 64M
    

Results

You have an app running in Cloud Foundry called "my-app".

You now can Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance.

Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance

Your application needs the Bosch IoT Permissions API endpoint URL as well as a Client ID and a Client Secret. This information allows to issue requests to our API. The information is provided to your application, when you bind it to your Bosch IoT Permissions service instance.

Preconditions

Procedure description

Our example assumes your IoT application is named my-app and your Bosch IoT Permissions instance is named my-permissions.

  1. Bind your app to the service instance with the bind-service command:

    cf bind-service my-app my-permissions

    While:

    • my-app - is the name of your application which runs in Cloud Foundry
    • my-permissions - is the name you gave your Bosch IoT Permissions service instance
  2. Once the Service instance is bound to your application, the service credentials will be stored in the system provided environment variable VCAP_SERVICES.
    Use the env command to get the environment variables of your bound application my-app:

    cf env my-app

    The result should contain a section like the following one:

    System-Provided:
    {
     "VCAP_SERVICES": {
      "im3-service": [
       {
        "credentials": {
         "imAdminUiUrl": "https://permissions.s-apps.de1.bosch-iot-cloud.com/admin?imtid=168276b0-3b41-11e5-ab75-d6cc6094be34",
         "imApiKeyId": "4b40f308-3402-4065-81ee-9424b5cbd427",
         "imClientId": "869eb850-3b41-11e5-ab75-d6cc6094be34",
         "imClientSecret": "3G8xMUKtWaxb1X7EcQY5io",
         "imLoginUrl": "https://permissions.s-apps.de1.bosch-iot-cloud.com/self-service/login?imtid=168276b0-3b41-11e5-ab75-d6cc6094be34\u0026ssoTargetUrl=%2Fprofile",
         "imServerUrl": "https://permissions-api.s-apps.de1.bosch-iot-cloud.com",
         "imTenantId": "168276b0-3b41-11e5-ab75-d6cc6094be34"
        },
        "label": "im3-service",
        "name": "my-im3-test",
        "plan": "Free",
        "tags": [
         "im3-service",
         "identitymanagement"
        ]
       }
      ]
     }
    }


    These variables are provided as binding information to your application:

    • imAdminUiUrl
      The URL of the administrative user interface, which provides you the possibility to manage the users, groups, roles and permissions of your tenant as well as the tenant relations to other tenants.
    • imApiKeyId
      An API Key for your Bosch IoT Permissions service instance. You can use this API Key ID to authenticate at your service instance.
    • imClientId
      An ID which identifies your bound application inside the Bosch IoT Permissions service.
    • imClientSecret
      A Client Secret which belongs to the Client ID.
    • imLoginUrl
      The URL to the Bosch IoT Permissions Login dialog with the user profile as target.
    • imServerUrl
      Send requests to the Bosch IoT Permissions API to this endpoint
    • imTenantId
      You need this Tenant ID to authenticate with your initial user at your service instance.
  3. In general your application needs the following binding information for API requests:

    • imServerUrl
    • imClientId and imClientSecret combined to a Client Access Token.
      This token must be sent with every request in a HTTP header x-im-client-access-token with value imClientId:imClientSecret.

    • imTenantId

Results

You have valid Bosch IoT Permissions credentials available.

You now may proceed with one of the following:

Get a Client Access Token

In case your application is deployed within Cloud Foundry please follow the instructions at Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance.

Migration from IM Server to the cloud service

The Bosch IoT Permissions service - also known as Identity Management, or IM3 - is available in the Bosch IoT Cloud.

In case you are already familiar with the IM concepts and need to migrate from your local IM server to our cloud offering, please follow the steps described in this chapter.

New features available in the service

Starting with version 4.x, there are several new features and concepts available. IM3 is provided under the name "Bosch IoT Permissions service" as a fully-managed cloud service. The following diagram shows a schematic view on the offering in the cloud:

Features of IM Server which are not provided in the service

Following concepts known from previous versions (e.g. IM 3.7) are not supported by the Permissions cloud service:

  • Masquerade as another user
  • LDAP as external identity provider

Other functional changes in the Permissions cloud service:

  • Application names must be globally unique
  • Domain entity is still supported in API 1, but not relevant any more in API 2

Get a service instance and migrate your data

In order to use the Bosch IoT Permissions service first of all you will need an account and space in the Bosch IoT Cloud.
Then you can follow the instructions in section Getting started - Bosch IoT Cloud to get your own service instance.

As result you will, have an own Bosch IoT Permissions Tenant available. You can start using the Permissions API, but be sure to Update your REST request headers.

Please contact service-permissions@bosch-si.com for further options on migrating your data into the your new Tenant.




Update your REST-based Java Client

If you are using an IM REST-based Java client in your applications, please update the artifact version to the latest available.

Starting with version 4.x, Identity Management provides two different client artifacts to access IoT Permissions' API 1:

Both im-api1-client and im-api1-client-cf expose the same API, thus you can use the client as you did before.

Further reading:

Find all configuration properties at API 1 Client for Java.

Find examples at Examples Using the API 1 Client for Java.



Update your REST request headers

If your application was using plain REST calls or the IM JavaScript support artefact, please consider its new endpoint in the cloud:

  • The current Service API 1 is exposed from the service at URL: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest
  • The current JavaScript REST API is exposed at URL: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/js/1/rest/

Additionally to the authentication mechanism which works as in the versions before the new Client Access Token header needs to be set:

Name: x-im-client-access-token

Value: clientId:clientSecret

In order to retrieve a client ID and secret for such an application which will not be deployed in the cloud please proceed as described at Push a trivial application to which you can bind and Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance.

Service Management

This section describes operations on your Bosch IoT Permissions service instance in the Bosch IoT Cloud. If you don't have a service instance, please refer to section Getting started - Bosch IoT Cloud to create your own service instance.

Change the Service Plan of your Bosch IoT Permissions instance

In case you exceed the limitations of the service plan you booked initially, you should change to the next higher one.
You can do this within the Cloud Foundry Apps Manager or via Cloud Foundry command line tool as described below.

At this point we assume you Bosch IoT Permissions instance is named my-permissions.

  1. Log in to the Cloud Foundry infrastructure and select the space where your application is running. 
    Please refer to section "Login" in the Cloud Foundry documentation > Getting Started with the cf CLI for more information on this step.
  2. Display the service metadata with the following command

    cf service my-permissions

    The result should look similar to the following one:

    Service instance: my-permissions
    Service: im3-service
    Tags:
    Plan: Free
    Description: User management, role-based access control and multitenancy for IoT applications.
    Documentation url: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/app/im-docu-spec
    Dashboard: https://permissions.s-apps.de1.bosch-iot-cloud.com/fusion/?imtid=<YOUR-TENANT-ID>
     
    Last Operation
    Status: create succeeded
    Message:
    Updated: 2016-03-04T15:09:07Z
  3. Change the service plan with an update-service command.
    Our example assumes you have a "Free" plan and want to change to "Starter".

    cf update-service my-permissions -p Starter

    The result should look similar to the following one:

    Updating service instance my-permissions as <your@email.com>...
    OK

    However, you could also book directly the "Standard" plan instead. 

Changing backwards (e.g. from Standard to Free) is also possible, but please keep in mind that our service broker does not check if your amount of tenants or users is in accordance with the target plan.

Result

You have changed the plan of your service instance.

Transfer a service instance into a new Cloud Foundry space

When you created a Bosch Iot Permissions service instance, it is managed inside Cloud Foundry space. You may want to move your service instance into an other space while retaining any data managed within your service instance. You can also transfer your service instance into a new Cloud Foundry "org" and from a BIC 1.0 to a BIC 2.0 org.

The procedure of such a service transfer contains the following steps:

  • Create a Transfer Key
  • Use the transfer key for creating a new service instance
  • Bind your application to the new service instance
  • Delete the original service instance

Please follow the detailed instructions below, if you need to transfer a service instance to a new space.

Preconditions

  • Cloud Foundry command line tool "cf" is installed
  • You have subscribed to the Bosch IoT Permissions service in BIC 1.0

    The service transfer feature is supported for the Service "Bosch IoT Permissions" in the Cloud Foundry Marketplace of BIC 1.0. It will be available for the Service "Bosch IoT Permissions" in BIC 2.0.
    It is not supported for the service "Bosch IoT Permissions - test-temp" in BIC 2.0.

Procedure Description

  • Create a Transfer Key
    Create a "Transfer Key" for your original service instance by calling the Cloud Foundry Service Key API (with Cloud Foundry command line tool "cf")
    Create the key with this command:

    cf create-service-key my-permissions-original transfer -c "{\"type\":\"transfer\"}"

    Retrieve the key for step 2:

    cf service-key my-permissions-original transfer

    Example result:

    { "transfer-key": "eyJhbGciOiJSU..." }
  • Use the transfer key for creating a new service instance
    Create a new service instance in the target space and supplying the Transfer Key as custom parameter. Your Bosch IoT Permissions data will be available within this new service instance,

    Inside the target space, create the service instance with this command:

    cf create-service im3-service <plan-id> my-permissions-transferred -c "{\"transfer-key\": <transfer-key-value>}"

    The <plan-id> is one of "Free", "Starter" or "Standard". Please make sure that you use the same plan-id as in your original service instance.
    The <transfer-key-value> is the one retrieved within step 1.

    Use Cloud Foundry web console in BIC 2.0

    If you transfer the service instance into a target space at BIC 2.0, you can also use the Cloud Foundry web console instead of the Cloud Foundry command line tool cf.
    When you create the service, click on the button "Show Advanced Options" and provide the transfer-key parameter (see screenshot).

    Use the transfer key only once

    The transfer key could only be used one time. If you have successful transferred the service and you noticed a failure at the new service instance (e.g. selecting the wrong target space), then complete the transfer and start a new transfer from the instance with the failure to a new one. If you delete the target service instance with the failure all your data gets lost!

  • Bind your application to the new service instance

    Bind your app to the service instance with the bind-service command:

    cf bind-service <my-app> my-permissions-transferred

    A detailed description of the binding operation can be found in section "Bind your application running in Cloud Foundry to your Bosch IoT Permissions service instance".

    Now the service instance is usable from the original space and the target space simultaneously until the service instance of the original space is deleted.‌

  • Delete the original service instance
    Deleting your original service instance will just remove it from the original space. It will not delete any of your Bosch IoT Permissions service data.

    Delete your original service instance with this command:

    cf delete-service my-permissions-original

    Double check the instance name and make sure you delete the original service instance!
    All service instance data will be lost, if you apply this command on an the new service instance.

Results

  • You have transferred your service instance into a new space
  • Your application is running in the new space and is bound to the service instance
  • Your service data is preserved and available to your application

Concepts

Client Access Token

All resources of Bosch IoT Permissions are protected via a Client Access Token based authentication. This token is used to authenticate your application at the service.
The token consists of a client ID and a client secret.

  • The client ID will be used for references with usage statistic data and accounting data.
  • The client secret will be stored as hashed value in the Bosch IoT Permissions system, so only the bounded application knows the client secret in plain text. 

It is essential that the received Client Access Token is kept secret and that it is only used by the bounded application or related components. It is therefore highly recommended to pass the token into the application via an environment or system variable and not to store it in the source code and especially not in JavaScript code which is executed in the Web browser.

If you want to use one of the Bosch IoT Permissions APIs via browser-side JavaScript, you can use a proxy to add the header to each request. Find an example at Example for exposing the API to client-side UI applications.

The token must be given for each server request via the HTTP header x-im-client-access-token. The header value contains the client ID and the client secret separated by a colon: clientId:clientSecret.

Get a Client Access Token

You can get a client a Client Access token either by binding your application in Cloud Foundry or via Service Management UI. For details see Get a Client Access Token.

Data Ownership

Bosch IoT Permissions is fully multitenancy ready and offers the option to work across tenant boundaries in a defined manner.

Multitenancy as a principle

Multitenancy is the capability of a single application instance to handle different tenants while the strict separation of their data is ensured.

This principle is fully implemented by IM: all entities belong to one tenant in order to separate the data and services between tenants. Thus, a tenant's data (e.g. user, groups, roles etc.) and services (e.g. applications and application data) are by default not visible to other tenants (data segregation). As a result, each tenant can manage his own data and his offerings to other tenants. However, privileged tenants can create further tenants and administrate them.

Managing relationships between tenants

Tenants that would have collaboration contracts in the real world, can additionally offer permissions/roles to be used by other tenants. While sharing data and service between tenants IM transparently allows to bind the scope to the providing or consuming tenant

  • Sharing Services - Offering applications to other tenants
    The possibility of a provider tenant to offer other tenants access to his applications goes hand in hand with the multitenancy principle. Thus each consuming tenant has its own data-store of the data resulting from using the application. 
  • Sharing Data - Acting on behalf of another tenant
    The possibility of a provider tenant to delegate tasks to another tenant is given by binding the scope to the provider. For such cases IM allows privileged tenants to transparently act on behalf of the provider.

A detailed description and examples can be found at Tenant Relation.

Basic Entities

The following figure introduces the basic entities managed within Bosch IoT Permissions.

The following sections describe all basic entities in detail:

Tenant

A tenant is a legal organizational unit that is generally the representative of a company.

Within the Web user interface, the following icon is used for a tenant .

There is a default tenant, i.e. the tenant where the IM itself is installed.
(The name of this tenant is set as "DEFAULT", however it can be changed before the first installation of the IM.)

When managing a tenant, keep the following concepts and restrictions in mind:

  • A tenant's name must be unique within Bosch IoT Permissions and may consist only of upper-case letters, underscores, and digits.
  • A tenant is the "owner" of all entities created using that tenant (this is also true for any tenants that are created).
  • A tenant can be marked as "deleted", in which case the entity will not appear on the user interface, neither will it be considered in lists, queries etc. (except for the "recycle bin" view).
  • Deleting a tenant includes deleting its whole organizational structure (incl. groups, users, roles, and all other entities owned by this tenant), as well as all tenants created by this tenant, and all existing relations to other tenants, domains, etc.
  • Moreover, a deleted tenant can only be restored by a user who has update-tenant permission in the context of the tenant that created this tenant (owning tenant).
  • A user who has read-, update-, delete-, or erase-tenant permission for a tenant can perform these operations also on any tenants created by this tenant.
  • Depending on the permissions assigned, a tenant can be allowed to manipulate other tenant's data.

User

A user can be a human being, machine, network, etc. that is allocated to use a part of an application.

Within the Web user interface the following icon is used for a user . A user provided by an external system is represented by the following icon .

A default user is generated during the initialization of a Bosch IoT Permissions service instance. This user is granted the role "Administrator" and is usually responsible for creating and managing all other entities.

When managing a user, keep the following concepts and restrictions in mind:

  • Each user belongs to exactly one tenant.
  • Each user is implicitly assigned to the All Users Group of the tenant he belongs to.
  • The user's name must be unique within that tenant.
  • The set of permissions that a user holds is a union of all permissions from:
    • user - group assignments
    • user - role assignments.
  • A user can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a user also deletes all his existing relationships to groups, roles etc.
User related information

There are two locations where user related information is stored: the user entity and user attributes related to the user entity.

User entity

The user entity holds some basic information about the user, e.g.:

  • First name
  • Last name
  • Email address
User attributes

A user attribute allows to store additional project specific user information. In addition to the basic user properties (user name, first name, last name, etc.) multiple custom user attributes can be added to a user (e.g. birthday, mobile number, etc...).

The data structure of a user attribute is a key-value pair with a type.

Example: Date of birth
Key: BDAY
Value: 19720415
Type: vCard4

See chapter Create an User Attribute using the Service API 1 for more information on user attributes.

In order to share user attributes between applications we recommend to define user attributes according to the vCard standard in version 4 and use "vCard4" as type.

Bosch IoT Permsissions defines a set of such user attributes which describe the User Profile.

User Profile

The User Profile consists of several user attributes. The key-value pairs which are used in the User Profile are defined in this section.

The format of these pairs is based on the vCard version 4 standard [RFC 6350].

These statements apply to the User Profile in general:

  • All user attributes of the profile have the type "vCard4".
  • When storing user attributes our service does not verify the value format.
  • Your are encouraged to store the values in the format as shown in the table below
  • Keys may contain additional vCard params (e.g. "VALUE=uri").
    The Bosch IoT Permissions service will return a key-value pair, if at least the vCard params are present as shown in the table below.
    It is possible that a returned key has additional parameters (e.g. geo location, media type, etc.)
User Profile attribute Description User attribute key
(including vCard params)
User attribute value format User attribute value example
Picture URL of the end-user's profile picture.
PHOTO
URI
http://example.com/myimage.png

Gender

End-user's gender.

GENDER
String

Possible values are "F" and "M". Other values may be used when neither of the defined values is applicable. In this case any value other than "F" and "M" is interpreted as "O" (other).

F
Birthdate End-user's birthday.
BDAY
YYYYMMDD
19720415
Language End-user's preferred language.
LANG
Language tag, as defined in [RFC 5646].
en-us
Phone End-user's preferred telephone number.
TEL;VALUE=uri
Phone number URI, as defined in [RFC 3966]
tel:+49-55555-5555
Cellphone End-user's preferred cellphone number.
TEL;VALUE=uri;
TYPE=cell
Phone number URI, as defined in [RFC 3966]
tel:+49-55555-5555

Address

End-user's preferred address.
ADR
;;[street];[city];;
[postal code];[country]
;;42 Plantation St.;Baytown;;
30314;United States of America

Website

URL of the End-user's Web page or blog.

URL
URI
http://example.com/myhomepage.html
Multiple entries for a User Profile attribute

Some user attributes may occur multiple times e.g. address. In this case the service expects that the key contains a preference parameter (PREF).
The preference parameter allows to order the values by preference. The most preferred user attribute's value is the one where the user attribute's key contains "PREF=1". Higher PREF values correspond to a lower level of preference.
For the User Profile, our service will select the key-value pair:

  • with the lowest PREF value, if there are multiple entries,
  • without PREF value if there is only one entry.

Example:

Entry A - key: ADR;PREF=2 - value: ;;42 Plantation St.;Baytown;;30314;United States of America

Entry B - key: ADR;PREF=50 - value: ;;100 Waters Edge;Baytown;;30314;United States of America

Entry A will be used for the User Profile because it has a lower PREF value.

To keep consistent with RFC 6350, Section 5.3., no entry will be returned in case:

  • there is no entry,
  • there are multiple entries but none of them contains a PREF value,

  • there are multiple entries with the same lowest PREF value.


User self-registration

Bosch IoT Permissions provides a Web based user self-registration application which can be used as a default implementation or as a template for custom registration forms.
The Web application also contains a login form with password reset functionality.

The self-registration process is a sequence of three use cases:

  • User self-registration:
    • The user creates a new user account by filling out a registration form.
      • Required fields are: username, email address and the initial password.
      • The ID of the tenant is provided via the URL.
      • The browser language is stored in form of a user attribute.
    • The user submits the registration request to the Bosch IoT Permissions service.
    • The service validates and stores the given data.
  • Send activation email:
    • After the form was submitted successfully to the service, the Web application triggers the service to send an activation email to the given email address.
    • The email contains an activation link which contains the user ID, the tenant ID and an activation code.
  • Activate user account:
    • After receiving the activation email, the user needs to click the link prepared within the activation email to continue the self-registration.
    • By following the link within the activation email the user is delegated to a Web site provided by the user self-registration Web application.
    • The site has a button which needs to be pressed by the user to trigger the activation. It uses the user ID and the activation code to activate the user at the Bosch IoT Permissions service.
      The response of this call is used to pre-fill the login form with the name of the user. The tenant ID is passed within the URL.
    • The user account is active from now on and the user is therefore able to login at Bosch IoT Permissions service from now on.
Privileged Users

The concept of privileged users allows to mark specific users as privileged. As a result those users are able to perform some operations which other users are not allowed to perform.

The main reason for this concept is to restrict critical operations to a very limited set of users.
All other users should e.g. not be able to assign additional permissions to themselves (permission escalation) or to delete a privileged user.

Privileged Users
  • Privileged users who are able to create assignments between entities can use all entities for these assignments.
    This means that a privileged user is even able to assign additional permissions to himself or to some other user (e.g. via some role).
  • By default the administration user of each tenant is marked as privileged.
  • Only privileged users are able to create, update or delete other privileged users.
Non-privileged Users
  • Non-privileged users which are able to create assignments between entities can do this only if the action does not (implicitly) exceed the set of own permissions:
    • They can only assign a permission to a role if they have this permission themselves.
    • They can only assign a role to a user if the role contains only permissions which they have themselves.
    • They can only assign a role to a group if the role contains only permissions which they have themselves.
    • They can only assign a user to a group if the group (indirectly) contains only permissions which they have themselves.
    • They can only assign a parent group to a group if the parent group (indirectly) contains only permissions which they have themselves.
    • For all other entities there is no such restriction as these can not be used as part of a permission escalation scenario.

When installing, updating IM, or creating a new tenant the privileged flag will be set to all users, which are directly assigned to the IM Administrator role or the IM Tenant Administrator role.

Group

A group is an organizational unit that is useful for grouping together users with similar functions.

Within the Web user interface the symbol used for a group is .

As groups are ordered hierarchically, each group that includes sub-groups is called a parent-group. A user who is assigned to a particular group is automatically also a member of all higher-ranking groups in the hierarchy.

When managing a group, keep the following concepts and restrictions in mind:

  • Each group belongs to exactly one tenant.
  • The group's name must be unique within that tenant.
  • The set of permissions that a group holds is a union of all permissions from:
    • group - role assignments
    • roles assigned to the group's parents in the hierarchy.
  • A group can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a group also deletes
    • all existing relations to users, roles etc.
    • all sub-groups and their assignments.

The All Users Group is created for every tenant automatically and behaves slightly different than common groups:

  • All users of this tenant are assigned to this group automatically.
  • Within the Web user interface the symbol used for this group is .
  • You will not be able to manually add or delete the membership to this group.
  • You will not be able to create sub-groups of the All Users Group.
  • You will not be able to delete the group explicitly. However, when deleting and/or permanently deleting a tenant, its "All Users" group will also be deleted.
  • You will not be able to restore the group explicitly. However, when restoring a tenant this group will also be restored.

As an administrative user, you can add all roles your users will need to this group, thus defining a set of rights which all users of your tenant will be granted automatically.

Role

A role is a job function within the context of an organization. The associated semantic regards rights and duties (the authority and responsibility) conferred on the user to whom the role is assigned. Usually, a role encapsulates a range of permissions that are necessary to perform its function.

A role can be defined either by a tenant or by an application. While application roles are delivered as part of the application, tenant roles are created by an administrator user. In the Web user interface, the following icon is used for representing a tenant role . A role provided by an application is marked by the following icon  and cannot be modified in the Web user interface.

There are predefined roles that are generated during the service instantiation, namely  "ServiceAdministrator",  "ApplicationInstaller", "RoleManager","TenantAdministrator", "TenantManager" and "UserManager".

When managing a role, keep the following concepts and restrictions in mind:

  • Each role has exactly one tenant or one application instance responsible for its creation.
  • The tenant role's name must be unique per tenant.
  • The application role's name must be unique per application.
  • A role can group permissions, and the same permission can be assigned to multiple roles.
  • A tenant role can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries etc. (except for the "recycle bin" view).
  • Deleting a role does not delete the permissions themselves but the association of these permissions to users, groups, etc.

As already mentioned, a role can be created either by an application instance or by a tenant. Furthermore, a role can be directly owned by the utilizing user's tenant, or it can be indirectly granted from another tenant. (For further information, please refer to Entities to describe relations between tenants). However, regardless of how a role is created and utilized, when referring to a role in this document with no explicit differentiation, an organization unit for managing a set of permissions is simply in mind.

Permission

A permission is a fine-grained concept for granting access to operations and/or data. Usually, a role encapsulates a set of permissions that are required for performing its tasks.

Within the Web user interface, the following icon is used to indicate a permission .

There is a set of predefined permissions to facilitate the management of the service instance (e.g., "CREATE_TENANT", "CREATE_USER", "DELETE_USER", etc.). These permissions are grouped already for the default roles e.g. "ServiceAdministrator",  "TenantAdministrator" etc.. The default tenant administrator, for example, needs all permissions to set up users, groups roles and to relate them. In order to delegate some duties to other users, the administrator can easily assign roles, such as the "RoleManager" role, to further administrator users.

Currently, the Administrator UI will not assist you in creating permissions. They are delivered as part of the applications.

When managing a permission, keep the following concepts and restrictions in mind:

  • Each permission has exactly one application instance responsible for its creation.
  • A permission's name must be unique per application.
  • The same permission can be assigned to multiple roles.
  • Deleting a role does not delete the permissions themselves but the association of these permissions to users, groups, etc.

Domain

A domain is an infrastructure entity that defines a realm of administrative autonomy, authority, or control within the Bosch IoT Permissions service.

Within the Web user interface, the following icon is used for a domain .

There is a default domain assigned to the default tenant that is reserved for the IM instance itself.
(The default the name is "IAP".)

Usually, the main task of a domain is to group the application instances whose authorization is to be managed.

When managing a domain, keep the following concepts and restrictions in mind:

  • A domain's name must be unique per tenant.
  • A domain can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting a domain will also delete all application instances, their roles, permissions, etc.

Application Instance

An application instance is a logical instance (e.g. one installation of a business application) that defines permissions and roles and uses the Bosch IoT Permissions authentication and authorization services.

Within the Web user interface, the following icon is used for an application .
Currently, the user interface will not support you with creating or updating an application instance.

There is a default application instance (assigned to the default domain and the default tenant) that is reserved for the Identity Management application itself.
(The default name is "IM", however, this initial name can be configured before the first Service installation. The default role to grant all permissions, which are necessary for an administrator user to be able to install an application instance, is "ApplicationInstaller".)

When managing an application instance, keep the following concepts and restrictions in mind:

  • An application instance's name must be unique per Permissions service and may not contain the pipe (|) nor the paragraph ($) character.
    Entities related to application instances (instance roles, permissions, offerings) also need to consider not using these characters.

  • The application instance's name should be named like the product or solution.
    In case of various installations, please use a talking prefix or ending (e.g. MySolution for the production installation and MySolution_Test for the test installation). It is therefore recommended to make the application instance name configurable. The configured value must then be used in permission or role checks. This enables the application to be registered multiple times at the same Permissions service with distinct names.
  • Deleting a domain will also delete all application instances, their roles, permissions, etc.

  • Deleting an application will also delete all application roles, permissions, etc.

  • The owner of an application instance is a tenant (i.e. the domain owner).

  • The application itself is responsible for defining the roles and permissions to properly restrict the execution of the application's operations.
    Bosch IoT Permissions only checks whether the user trying to perform a task has the required permissions (especially if the user's context covers more than the data of the tenant to which he belongs).

Entities to describe relations between tenants

IM offers increased support for multi-tenancy. In addition to the strict data separation for multiple tenants hosted within the same database, IM also allows the definition of relationships between tenants.

This feature enables tenants to share data and permissions with each other in a controlled way. Thus, a "consumer" tenant so empowered by another one can act on behalf of that "provider" tenant, accomplishing contracts similar to agents.

IM allows the definition of relationships between tenants by using the entity Tenant Relation:

Tenant Relation

In addition to the strict data separation for multiple tenants hosted within the same database, IM also allows the definition of relationships between tenants.

General structure of a tenant relation

Like all other entities, a tenant relation is owned by a tenant.

This tenant (the providing tenant) can use a tenant relation to offer roles and permissions to other tenants (consuming tenants).

In order to do so, he must assign at least one offering to the tenant relation.

The applicable scope of the assigned offering defines whether the consuming tenant is either:

  • provided with service access (protected by IM roles and permissions) that he can apply on his own/consumer data (scope is CONSUMER) or
  • provided with provider data access (scope is PROVIDER) including the necessary service access in order to do so.

Note

Scope provider does not include scope consumer, i.e. if a tenant has to manage its own data with a service and the data of another tenant with the same, he has to be provided with the service by the service-owning tenant (scope CONSUMER) and data access by the data-owning tenant (scope PROVIDER).

The following diagram shows the general structure of a tenant relation, including possible assignments to/between the entities offering, role, and permission.

Examples of tenant relations
Tenant allows another tenant to manage users for him (Principal-Agent Relationship)

This example shows the usage of an IM tenant relation to provide data access to another tenant.

  • This tenant relation would allow Tenant T_Y (i.e. the Agent) to administrate the users of Tenant T_X (i.e. the Principal).
  • The applicable scope for the offering is PROVIDER.

To put it another way: Tenant T_Y has the permissions to create, modify, and delete users in the data store of Tenant T_X.

Tenant extends a software service to another tenant (Service Provider-Consumer Relationship)

This example shows the usage of an IM tenant relation to provide extended service access to another tenant. The service in this example is IM itself and it shows that IM uses the tenant relationships internally as any external application would do.

  • This tenant relation provides IM permissions from Tenant T_X (i.e. the Service Provider) to Tenant T_Y (i.e. the Service Consumer) to manage further child tenants in addition to the standard offering for user/group/role management.
  • The applicable scope for the offering is CONSUMER.

To put it another way: Tenant T_Y has the permissions to create, modify, and delete child tenants in its own data store.

Offering roles and / or permissions

An offering can contain either roles, permissions or a combination of roles and permissions.

With the help of the following table you should be able to find out what fits best for your scenario:

Offering contains Effect for the consuming tenant When to use
only permissions He is able to assign the permissions to his users via groups or roles (which he needs to create on his own).
  • Your application has no standard / useful roles that can be offered.
only roles He is able to assign the roles to his users, thus enabling them to use the role and the contained permissions.
He is not able to see or modify the contained permissions.
  • You want to be able to change contained permissions transparently.
  • Your application has no permissions (it provides only roles).
roles and permissions

He is able to assign the roles to his users, thus enabling them to use the role and the contained permissions.
He is able to assign the permissions to his users via groups or roles (which he needs to create on his own).

  • This is the most flexible approach but it might not be appropriate when the permissions which are contained in the offered roles are likely to change often.
Propagation of offered roles and permissions

When roles and permissions are offered to a consuming tenant, this tenant can use these on his own data (scope CONSUMER) or on the data of the providing tenant (scope PROVIDER).

But what happens if the consuming tenant has the permissions required to establish tenant relations and creates one which includes the offered roles or permissions, i.e. somehow forwards the permissions granted to him to third parties?

The following table shows the effects of an offering chain:

  • Tenant A (T_A) to Tenant B (T_B)
  • Tenant B (T_B) to Tenant C (T_C)
Scope of the Offering
from T_A -> T_B

Scope of the Offering
from T_B -> T_C

Effective Roles / Permissions available for T_C
PROVIDER CONSUMER / PROVIDER T_B is not allowed to use the roles / permissions on his own data and therefore is also not able to propagate them to T_C.
CONSUMER CONSUMER T_B is allowed to use the roles / permissions on his own data but he is not allowed to propagate them to T_C to use the roles/permissions on T_C's data.
CONSUMER PROVIDER T_B is allowed to use the roles / permissions on his own data.
T_B is also able to propagate the roles / permissions. As a consequence, T_C is enabled to use them on the data of T_B.

This means that a consuming tenant T_B, which has the permissions required to establish tenant relations, is able to propagate roles and permissions to another tenant T_C. But the latter is only able to use those roles and permissions if they were offered to T_B with scope CONSUMER and were propagated to T_C with scope PROVIDER.
All other combinations are not valid, and T_C will therefore not be able to see or use them.

For example:

  • The application IM is owned by T_A. 
  • T_A allows T_B to create, update, and delete its own users (scope CONSUMER) by an according relationship.
  • T_B can now give T_C the permission to read its own users (scope PROVIDER), i.e. T_C can read users of T_B.

When a providing tenant (T_A) removes a role / permission from an offering, all direct (T_B) and indirect (T_C) consuming tenants are no longer able to see or use it.

The same applies when the tenant relation associated with the offering is or becomes invalid (e.g. end date is reached) or is deleted / erased.

Offering

An offering is a set of roles and permissions that can be offered by one tenant to others. Thus, an application registered at our Bosch IoT Permissions service can spread its roles and permissions outside the boundaries of the owning tenant. Further, the offering can combine roles and permissions that come with IM, or an application instance registered at our Bosch IoT Permissions service, or self-generated roles (using the Web user interface).

Within the Web user interface, the following icon is used for representing an offering .

When managing an offering, keep the following concepts and restrictions in mind:

  • Each offering has exactly one owner (i.e. the providing tenant, who created the offering). The offering's name must be unique within this tenant.
  • The offering's permission is a union of all permissions granted:
    • directly
    • via a role.
  • The offering has exactly one applicable scope ( ApplicableScope), i.e. the definition of the context in which an offered permission or role is applicable.
    • Applicable scope PROVIDER: The permissions will affect the data of the providing tenant.
      Using this scope, the providing tenant can allow other tenants to act on his behalf.

    • Applicable scope CONSUMER: The permissions will affect the data of the consuming tenant.
      Using this scope, the providing tenant can allow other tenants to use his applications. The data resulting from using the application will be in the ownership of the consuming tenant.

  • An offering can be marked as "deleted". In this case the entity does not appear on the user interface, neither is it considered in lists, queries, etc. (except for the "recycle bin" view).
  • Deleting an offering will delete all existing assignments to the permissions, roles, and the tenant relations.

In order to become active, a so called Tenant Relation must be created, to which the offering can then be added.

The Bosch IoT Permissions service itself already provides a default offering. Thus, a basic set of IM roles and permissions is automatically offered to all tenants who book our service. This offering includes almost all the IM permissions, which enables the tenant with full identity management features.

Further Notes:

  • The entity's full name is OfferingType.
  • As part of the registration process of an application instance it is possible to add Offering Types containing roles and permissions which should be given to all tenants (enableAutoAssignment).  This functionality can only be used when registering an application instance in the context of the DEFAULT tenant.
  • To avoid confusion in case of various permissions using the same name but being part of different applications (or being exposed by instances of the same application running on different domains), the tenant getting the offering implicitly will be granted read permissions for the entities the permission/role comes from (e.g. tenant, application instance, domain).

Implicit Visibility

Nearly all operations in IM are protected by permissions in a way that a user without the corresponding permission is not able to perform the protected operation.

Nevertheless a basic set of operations can be performed without permissions.

This enables e.g. a user to retrieve or modify his own user without requiring an explicit permission.

  • User
    • A user without READ_USER permission is allowed to query his own user by ID and to query the user attributes which belong to his user.
    • A user without UPDATE_USER permission is allowed to update his own user (every update except unlocking is possible) and to create, update and delete the user attributes which belong to his user.

In addition there is an implicit visibility for entities which are (indirectly) involved in tenant relations. When roles and permissions are offered across tenant boundaries it may occur that their ownership is not obvious to all participants. Imagine for example two application instances, both offering a READ permission. How would a simple user find out on which application he really has read permission on?

If both application instances are owned by the same tenant that owns the simple user entity, this is easy, as his administrator most probably grants him as well the READ_INSTANCE permission. In that case, the IM UI allows reading the Applications (list). Activating the Pin icon on the permission or the application in question, the related entity gets highlighted. (Programmatically the relationToInstance predicate can be used).

However, in case the applications belong to another tenant or even different tenants, it might get more difficult to gather this information, unless each tenant owning one of the application instances granted READ_INSTANCE permission on his data (i.e. with applicable scope PROVIDER).

To avoid ambiguity in case a read permission was not granted explicitly, we provide an implicit visibility mechanism for the following entities:

  • Tenant (Provider and Consumer)
    • A user with READ_TENANT permission will see the tenants list within the UI. He is allowed to see his own tenant, the tenants created by his tenant (according to the pattern of seeing hierarchical groups), all tenants which offered roles or permissions to the tenant for which he is currently logged in (in order to see for which tenants a role or permission can be applied or from which tenant they were provided), all tenants which receive a tenant relation from the tenant for which he is currently logged in (in order to see which tenants can consume roles or permissions of this tenant), and his own parent tenant (the tenant who created the tenant).
    • A user without READ_TENANT permission will not see tenants in the Tenants list within the UI but in case he is able to act on behalf of another tenant, he is allowed to see his own tenant and all tenants for which he is able to act on behalf of.
  • Domain:
    • A user with READ_DOMAIN permission is allowed to see all domains to whose instances the roles and permissions belong which were offered to the tenant for which he is currently logged in (in order to see to which domain a role or permission belongs).
  • Application Instance:
    • A user with READ_INSTANCE permission is allowed to see all instances to which the roles and permissions belong which were offered to the tenant for which he is currently logged in (in order to see to which instance a role or permission belongs).
    • A user without READ_INSTANCE permission is allowed to see the instances to which his roles and permissions belong to.
  • Role:
    • A user with READ_ROLE permission is allowed to see all roles which were offered to the tenant for which he is currently logged in (e.g. in order to assign these roles to users).
  • Permission:
    • A user with READ_PERMISSION permission is allowed to see all permissions which were offered to the tenant for which he is currently logged in (e.g. in order to assign these permissions to roles).

Initial set of Bosch IoT Permissions entities

When the Bosch IoT Permissions service is started for the first time an initial set of entities is created automatically.

This set consists of the following entities:

Roles of IM

Following roles are created automatically:

  • IM Service Administrator: This role contains the set of permissions which is offered automatically to all new tenants. It is assigned automatically to the Admin user of the new tenant.
  • IM Application Installer: This role contains the set of permissions which is required to install/register new application instances in IM.
  • IM User Manager: This role contains the set of permissions typically needed to work with the customized "User Management" view.
  • IM Role Manager: This role contains the set of permissions typically needed to work with the customized "Role Management" view
  • IM Tenant Manager: This role contains the set of permissions typically needed to work with the customized "Tenant Management" view.
    Deviating from the Tenant Administrator role, this role has less permissions and focuses on defining relations between tenants (instead of managing all entities of the tenant). 

Permissions of Bosch IoT Permissions

The permissions which are created automatically are used to secure the functionality of the IM application itself. This means that only a user who has the required permissions is allowed to use the corresponding action in IM.

For nearly all types of entities there is a corresponding set of permissions which protects those actions which have a direct affect on the entity.

For the group entity there are e.g. the following permissions:

  • CREATE_GROUP: Allows to create groups.
  • READ_GROUP: Allows to query groups.
  • UPDATE_GROUP: Allows to create groups.
  • DELETE_GROUP: Allows to delete groups.
  • ERASE_GROUP: Allows to erase (i.e. permanently delete) groups.

The same set of permissions exists for most types of entities and protects the same functionality.

The same set of permissions exists also for the tenant entity but the protected functionality differs: 

  • CREATE_TENANT: Users with this permission are allowed to create additional tenants (incl. the creation of a user with role IM Tenant Administrator).
  • UPDATE_TENANT: Users with this permission are allowed to restore deleted tenants (incl. the creation of a user with role IM Tenant Administrator).

In order to establish or remove a relation between a user and a group the following permissions are required:

  • READ_USER
  • READ_GROUP and 
  • RELATION_USER_GROUP: Add or remove relations between users and groups.

The same schema applies to all other types of relations between entities which are supported by IM.

In addition IM creates the following special permissions which do not apply to the schema mentioned above: 

SELF_DELETE_USER: Users with this permission are able to delete themselves (by default this permission is not assigned to any role - as a result no user is able to delete himself by default).

INSTALL_APPLICATION: Users with this permission are allowed to install/register complete application instances (incl. offering types, roles and permissions) using the corresponding functionality.

EMAIL_TEMPLATE_ADMINISTRATION: Allows to create new and modify existing email templates. The email templates are used to compose emails which are send e.g. when a user wants to reset his password.

Groups

All Users Group: This group is created for every tenant automatically, and all users of the tenant are assigned to this group implicitly.
Initially this group has no assigned roles. By assigning roles to the All Users Group you specify the set of roles and/or permissions which should be available for every user of this tenant.

Protection of own Entities

All Bosch IoT Permissions specific entities are protected for manipulation. It is not possible to update, to delete or to erase an IM entity. It is also not possible to remove or to create new assignments between such protected entities. When trying to manipulate such entities or relations, an IMEntityManipulationException or an IMEntityRelationManipulationException will be thrown by the service.

Following IM entities which have some special rules:

  • The initial created user (Admin) can be updated, deleted and erased. When deleting or erasing this user another user should be available with the same assigned set of permissions.
  • The automatically created group All Users Group cannot be updated, deleted or erased. It is not possible to remove users from this group (all users are assigned) but it is possible to assign roles to this group.

Roles provided by IM

IM Service Administrator - Role
Role name IM Service Administrator
Description Service Administrator with almost all permissions
Permissions Find a list of all IM permissions at "Permissions provided by IM".
Technical name ServiceAdministrator
IM Application Installer - Role
Role name IM Application Installer
Description Install complete application instances
Permissions 4
Technical name ApplicationInstaller
Permission name Description Technical name
Application instances - install Users with this permission are allowed to install applications (incl. Roles and Permissions) INSTALL_APPLICATION
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Tenants - query Allows to query tenants READ_TENANT
IM Role Manager - Role
Role name IM Role Manager
Description Manages roles and permissions
Permissions 10
Technical name RoleManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'role-permission' relations Add or remove relations between roles and permissions RELATION_ROLE_PERMISSION
Permissions - query Allows to query permissions READ_PERMISSION
Roles - create Allows to create roles CREATE_ROLE
Roles - delete Allows to delete roles DELETE_ROLE
Roles - erase Allows to erase roles ERASE_ROLE
Roles - query Allows to query roles READ_ROLE
Roles - update Allows to update roles UPDATE_ROLE
Tenants - query Allows to query tenants READ_TENANT
IM Tenant Administrator - Role
Role name IM Tenant Administrator
Description

Administrator for a specific tenant

Permissions 27
Technical name TenantAdministrator
Permission name Description Technical name
API Key Administration Allows to manage own API Keys API_KEY_ADMINISTRATION
Activation code administration for the current tenant Allows to generate and read activation codes for
all users of the current tenant
ACTIVATION_CODE_ADMINISTRATION
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Email templates - create and modify Allows to create new and modify existing email
templates
EMAIL_TEMPLATE_ADMINISTRATION
Groups - create Allows to create groups CREATE_GROUP
Groups - delete Allows to delete groups DELETE_GROUP
Groups - erase Groups - erase ERASE_GROUP
Groups - query Allows to query groups READ_GROUP
Groups - update Allows to update groups UPDATE_GROUP
Modify 'group-role' relations Add or remove relations between groups and roles RELATION_GROUP_ROLE
Modify 'role-permission' relations Add or remove relations between roles and permissions RELATION_ROLE_PERMISSION
Modify 'user-group' relations Add or remove relations between users and groups RELATION_USER_GROUP
Modify 'user-role' relations Add or remove relations between users and roles RELATION_USER_ROLE
Permissions - query Allows to query permissions READ_PERMISSION
Roles - create Allows to create roles CREATE_ROLE
Roles - delete Allows to delete roles DELETE_ROLE
Roles - erase Allows to erase roles ERASE_ROLE
Roles - query Allows to query roles READ_ROLE
Roles - update Allows to update roles UPDATE_ROLE
Tenants - query Allows to query tenants READ_TENANT
Tenant-specific security settings Allows to create and modify tenant-specific security
settings
TENANT_SECURITY_ADMINISTRATION
Users - create Allows to create users CREATE_USER
Users - delete Allows to delete users DELETE_USER
Users - erase Allows to erase users ERASE_USER
Users - query Allows to query users READ_USER
Users - update Allows to update users UPDATE_USER
IM Tenant Manager - Role
Role name IM Tenant Manager
Description Manages tenant relations and offerings
Permissions 24
Technical name TenantManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Domains - query Allows to query domains READ_DOMAIN
Modify 'offering type-permission' relations Add or remove relations between offering types and permissions RELATION_PERMISSION_OFFERING_TYPE
Modify 'offering type-role' relations Add or remove relations between offering types and roles RELATION_ROLE_OFFERING_TYPE
Modify 'role-permission' relations

Add or remove relations between roles and permissions

RELATION_ROLE_PERMISSION
Modify 'tenant relation-offering type' relations Add or remove relations between tenant relations and offering types RELATION_TENANT_RELATION_OFFERING_TYPE
Modify 'tenant relation-tenant' relations Add or remove relations between tenant relations and tenants RELATION_TENANT_RELATION_TENANT
Offering types - create Allows to create offering types CREATE_OFFERING_TYPE
Offering types - delete Allows to delete offering types DELETE_OFFERING_TYPE
Offering types - erase Allows to erase offering types ERASE_OFFERING_TYPE
Offering types - query Allows to query offering types READ_OFFERING_TYPE
Offering types - update Allows to update offering types UPDATE_OFFERING_TYPE
Permissions - query Allows to query permissions READ_PERMISSION
Roles - query Allows to query roles READ_ROLE
Tenant relations - create Allows to create tenant relations CREATE_TENANT_RELATION
Tenant relations - delete Allows to delete tenant relations DELETE_TENANT_RELATION
Tenant relations - erase Allows to erase tenant relations ERASE_TENANT_RELATION
Tenant relations - query Allows to query tenant relations READ_TENANT_RELATION
Tenant relations - update Allows to update tenant relations UPDATE_TENANT_RELATION
Tenants - create (incl. admin) Users with this permission are allowed to create additional tenants including the - create of an administrator role and user CREATE_TENANT
Tenants - delete Allows to delete tenants DELETE_TENANT
Tenants - erase Allows to erase tenants ERASE_TENANT
Tenants - query Allows to query tenants READ_TENANT
Tenants - update and restore Users with this permission are allowed to restore deleted tenants (incl. to create an administrator role and user) UPDATE_TENANT
IM User Manager - Role
Role name IM User Manager
Description Manages users, groups and roles
Permissions 16
Technical name UserManager
Permission name Description Technical name
Application instances - query Allows to query instances READ_INSTANCE
Groups - create Allows to create groups CREATE_GROUP
Groups - delete Allows to delete groups DELETE_GROUP
Groups - erase Groups - erase ERASE_GROUP
Groups - query Allows to query groups READ_GROUP
Groups - update Allows to update groups UPDATE_GROUP
Modify 'group-role' relations Add or remove relations between groups and roles RELATION_GROUP_ROLE
Modify 'user-group' relations Add or remove relations between users and groups RELATION_USER_GROUP
Modify 'user-role' relations Add or remove relations between users and roles RELATION_USER_ROLE
Roles - query Allows to query roles READ_ROLE
Tenants - query Allows to query tenants READ_TENANT
Users - create Allows to create users CREATE_USER
Users - delete Allows to delete users DELETE_USER
Users - erase Allows to erase users ERASE_USER
Users - query Allows to query users READ_USER
Users - update Allows to update users UPDATE_USER

Permissions provided by IM

English German
API Key Administration API Key Verwaltung
Activation code administration for the current tenant Aktivierungscodes für den aktuellen Mandanten verwalten
Application instances - install Applikationen anlegen (inkl. Rollen u. Berechtigungen)
Application instance roles - create Applikations-Rollen anlegen
Application instance roles - delete Applikations-Rollen löschen
Application instance roles - erase Applikations-Rollen unwiderruflich löschen
Application instance roles - update Applikations-Rollen bearbeiten
Application instances - create Applikationen anlegen
Application instances - delete Applikationen löschen
Application instances - erase Applikationen unwiderruflich löschen
Application instances - install Applikation anlegen (inkl. Rollen u. Berechtigungen)
Application instances - query Applikationen abfragen
Application instances  - update Applikationen bearbeiten
Client access token administration for the current tenant Client Access Token Verwaltung
Domains - create Domäne anlegen
Domains - delete Domänen löschen
Domains - erase Domänen unwiderruflich löschen
Domains - query Domänen abfragen
Domains - update Domänen bearbeiten
Email templates - create and modify E-Mail-Vorlagen anlegen und bearbeiten
Groups - create Gruppen anlegen
Groups - erase Gruppen unwiderruflich löschen
Groups - delete Gruppen löschen
Groups - query Gruppen abfragen
Groups - update Gruppen bearbeiten
Modify 'group-role' relations Verknüpfungen zw. Gruppen und Rollen
Modify 'offering type-permission' relations Verknüpfungen zw. Angeboten und Berechtigungen
Modify 'offering type-role' relations Verknüpfungen zw. Angeboten und Rollen
Modify 'role-permission' relations Verknüpfungen zw. Berechtigungen und Rollen
Modify 'tenant relation-offering type' relations Verknüpfungen zw. Gruppen und Rollen
Modify 'tenant relation-tenant' relations Verknüpfungen zw. Mandantenbeziehungen und Angeboten
Modify 'user-group' relations Verknüpfungen zw. Benutzern und Gruppen
Modify 'user-role' relations Verknüpfungen zw. Benutzern und Rollen
Offering types - create Angebote anlegen
Offering types - delete Angebote löschen
Offering types - erase Angebote unwiderruflich löschen
Offering types - query Angebote abfragen
Offering types - update Angebote bearbeiten
Own user - delete Eigenen Benutzer löschen
Permissions - create Berechtigungen anlegen
Permissions - delete Berechtigungen löschen
Permissions - erase Berechtigungen unwiderruflich löschen
Permissions - query Berechtigungen abfragen
Permissions - update Berechtigungen bearbeiten
Roles - create Rollen anlegen
Roles - delete Rollen löschen
Roles - erase Rollen unwiderruflich löschen
Roles - query Rollen abfragen
Roles  - update Rollen bearbeiten
Tenant relations - create Mandantenbeziehungen anlegen
Tenant relations - delete Mandantenbeziehungen löschen
Tenant relations - erase Mandantenbeziehungen unwiderruflich löschen
Tenant relations - query Mandantenbeziehungen abfragen
Tenant relations - update Mandantenbeziehungen bearbeiten
Tenants - create (incl. admin) Mandanten anlegen (inkl. Admin)
Tenants - delete Mandanten löschen
Tenants - erase Mandanten unwiderruflich löschen
Tenants - query Mandanten abfragen
Tenants - update and restore Mandanten wiederherstellen und bearbeiten
Tenant-specific security settings

Mandanten-spezifische Sicherheitseinstellungen

Users - create Benutzer anlegen
Users - delete Benutzer löschen
Users - erase Benutzer unwiderruflich löschen
Users - query Benutzer abfragen
Users - update Benutzer bearbeiten

Audit Logging

If you are interested in activating Audit Logging for your tenant, please contact our team via service-permissions@bosch-si.com.
The audit logging feature is not complete yet: audit logs can be written, however, there is no API providing you the possibility to download these logs.

Audit logging is a feature to realize legal requirements of your country related to handling of personal data. The Bosch IoT Permissions service allows to store personal data like the first name, the last name, the email address, and other data related to a user. There might be the requirement by law to audit who performs which changes at that personal data together with a timestamp which indicates when the changes were applied. 

The Bosch IoT Permissions Service provides an Audit Logging facility which is able to audit such events but also provides the possibility to log security related events like the assignment of a role to a user, adding the privileges flag to a user, changing the password of a user, and so on. Therefore the service provides two categories of audit logging: Audit Logging for Personal Data Privacy and Audit Logging for Security. 

The following list provides a quick overview about the supported audit log events per category:

Privacy Audit Logging

  • User creation / deletion / restore / erasure / erasure by system
  • Changes at user properties
  • User Attribute creation / deletion / update / bulk creation and update

Security Audit Logging

  • User creation / deletion / restore / erasure / erasure by system
  • Agent Credentials creation / erasure
  • Authentication and authorization for Service API 2
  • User locking and unlocking
  • Password changes
  • User activation
  • Changing the privileged flag of a user
  • Assigning a role to a user, a role to a group, a group to user, a permission to a role
  • Changing a group's parent
  • Removing an assignment between a role and a user, a role and a group, a group to a user, and a permission to a role

These two Audit Logging categories can be activated and deactivated independently per tenant.

Audit log entries are provided as JSON and might contain properties of type string, integer, boolean, array, as well as complex types. If the type differs from string, this is mentioned in the description of the property. Not every request to the IoT Permissions Service results in the same amount of audit log events. For example updating a user may result in an event for the user property change but also an event for the privileged flag change.

The following subsections describe the events which might be raised in detail whereby all events share the following set of properties:

Property Always present Description
cd yes Creation date of the audit log entry. The audit log entry is created at the time when the corresponding user action is performed.
tid yes The ID of the tenant for whom the audit log entry was written resp. who is affected by the change. For example the affected tenant of a user property change is always the tenant the user belongs to.
op yes Unique name of the operation which was performed to create the audit log entry.
puid yes The ID of the user who performed the operation. Usually this is the ID of the user who was authorized. For resources which are available without authorization, the performing user ID is derived from the context. For example when creating a self registered user the puid is equal to the ID of the user who was created.

An example event for an authorization would look like the following:


{
    "cd":"2017-06-30T20:52:40Z",
    "tid":"cbeaa370-c11d-11a1-8ba8-d4bea92ae488",
    "puid":"e7db57c0-0f0e-11a7-9510-f48c507b3019",
    "uid":"e7db57c0-0f0e-11a7-9510-f48c507b3019",
    "idtniss":"https://permissions.apps.bosch-iot-cloud.com/authentication",
    "authznid":"8554d063-653f-472f-ad00-2488bb386db9",
    "authznexp":"2017-06-30T20:52:40Z",
    "clientid":"cbeae375-c21d-12e1-8ba8-d4bed92",
    "claims":{
        "rn":{
            "MY_APP":["UserAdministrator","DeviceAdministrator"]
        },
        "pn":{
            "MY_APP":["READ_DEVICE","UPDATE_DEVICE",...]
        }
    },
    "op":"authorization"
}

Privacy Audit Logging

User creation

Operation value: user.created

Properties:

Property Always present Description
uid yes The ID of the created user.
name yes The name of the created user.
fname no The first name of the created user.
lname no The last name of the created user.
email no The email address of the created user.
extype no The property is only set If the user is not a user who is managed by the Bosch IoT Permissions service. The only valid value is JWT.
priv no

The property defines if the user was created with the privileged flag.

The boolean property is only provided if the value is set to true.

act no

The property defines if the user was marked as an active user.

The boolean property is only provided if the value is set to true.

pwprov no

The property indicates if the a password has been provided when creating the user. 

The boolean property is only provided if the value is set to true.

User deletion

Operation value: user.deleted

Properties:

Property Always present Description
uid yes The ID of the deleted user.
User restore

Operation value: user.restored

Properties:

Property Always present Description
uid yes The ID of the restored user.
User erasure

Operation value: user.erased

Properties:

Property Always present Description
uid yes The ID of the erased user.
User erasure by system

Operation value: user.erased.system

Properties:

Property Always present Description
uid yes The ID of the erased user.
Changes at user properties

Operation value: user.property_changed

Properties:

Property Always present Description
uid yes The ID of the user on whom the change was performed.
name no The new name of the user. If the existing value was changed to an empty value an empty string is used.
fname no The new first name of the user. If the existing value was changed to an empty value an empty string is used.
lname no The new last name of the user. If the existing value was changed to an empty value an empty string is used.
email no The new email address of the user. If the existing value was changed to an empty value an empty string is used.

At least one of the optional fields is set.

User Attribute creation

Operation value: user.attribute.created

Properties:

Property Always present Description
uid yes The ID of the user on whom the property was created.
key yes The key of the user attribute.
value yes The value of the user attribute.
type yes The type of the user attribute.
User Attribute deletion

Operation value: user.attribute.deleted

Properties:

Property Always present Description
uid yes The ID of the user for whom the property was deleted.
key yes The key of the user attribute.
User Attribute update

Operation value: user.attribute.updated

Properties:

Property Always present Description
uid yes The ID of the user on whom the property was updated.
key yes The key of the user attribute.
value yes The new value of the user attribute.
type yes The new type of the user attribute.
User Attribute bulk creation and update

Operation value: user.attribute.bulk

Properties:

Property Always present Description
uid yes The ID of the user on whom the property was created or updated.
attrs[] yes The array attrs contains a set of complex types. Each complex type defines a single user attribute of the user which was either created or updated.
attrs[].key yes The key of the user attribute.
attrs[].value yes The new value of the user attribute.
attrs[].type yes The new type of the user attribute.

Security Audit Logging

Security Audit Logging allows to keep track of all assignments of roles and permissions to users. But un-assignments are not always logged, e.g. if they occur due to deletion of roles, groups, permissions and tenant relations.

To check which roles and permissions were assigned to a user at a specific point in time, we recommend to analyse the audit log entries of authorization via Service API 2. These log entries contain the requested roles and permissions which were assigned to the user at that point in time


Security Audit Logging includes log entries for authentication and authorization of Service API 2. Authentication and authorization via API 1 (create/get identity context) is not logged.

Agent Credentials creation

Operation value: agent_credentials.created

Properties:

Property Always present Description
uid yes The ID of the user for whom the Agent Credential was created
acid yes The ID of the created Agent Credential
scopes[] no Array with string values of the scopes which could be used for issuing an Authorization Token
apps[] no Array with string values of the applications which could be used for issuing an Authorization Token
tag no The tag of the Agent Credential
exp no The expiration in seconds of the Agent Credential
Agent Credentials erasure

Operation value: agent_credentials.erased

Properties:

Property Always present Description
acid no The ID of the erased Agent Credential (present if erased by id)
acids[] no Array with string values of the IDs of the erased Agent Credentials (present if erased by refkey)
Authentication for Service API 2

Operation value: authenticated

Properties:

Property Always present Description
uid yes The ID of the user for whom the ID Token was issued.
idtnexp yes The expiration date of the ID Token as ISO-8601 string representation (example: 2017-07-03T12:03:44Z).
authcnmd yes

The authentication method. Valid values are:

  • agent_credentials: Agent Credentials are used for authentication. The property acid is set.
  • username_password: Basic Credentials with username, tenant, and password are used for authentication.
clientid yes The ID of the client used for authentication.
acid no The ID of the Agent Credentials used for authentication.
Authorization for Service API 2

Operation value: authorized

Properties:

Property Always present Description
uid yes The ID of the user on whom the Authorization Token was issued.
idtniss yes The issuer of the ID Token used for authentication.
authznid yes The ID of the issued Authorization Token.
authznexp yes The expiration date of the Authorization Token as ISO-8601 string representation (example: 2017-07-03T12:03:44Z)
clientid yes The ID of the client used for authorization.
claims no Map of claims except the claim tid which is already stored in the common event property tid.
claims.gid[] no Group IDs as array.
claims.trid[] no Tenant role IDs as array.
claims.rn no Map of application names as keys with an array of assigned role names as value.
claims.pn no Map of application names as keys with an array of assigned permission names as value.
claims.ctx no Flag which indicates that the Authorization Token may be used to request Identity Contexts of Service API 1.
claims.orig no Object with additional information about the ID token.
claims.orig.iss no The issuer of the ID Token used for authentication.
claims.orig.sub no The subject of the ID Token used for authentication.
claims.orig.aud no The audience of the ID Token used for authentication.
User locking

Operation value: user.locked

Properties:

Property Always present Description
uid yes The ID of the user who was locked.
User unlocking

Operation value: user.unlocked

Properties:

Property Always present Description
uid yes The ID of the user who was unlocked.
Password changed

Operation value: user.password_changed

Properties:

Property Always present Description
uid yes The ID of the user whose password was changed.
User activation

Operation value: user.activated

Properties:

Property Always present Description
uid yes The ID of the user who was activated.
Set a user to be privileged

Operation value: user.privileged

Properties:

Property Always present Description
uid yes The ID of the user who was privileged.
Remove the privileged flag from a user

Operation value: user.unprivileged

Properties:

Property Always present Description
uid yes The ID of the user whose privileged flag was removed.
Assigning a role to a user

Operation value: user_role.assigned

Properties:

Property Always present Description
uid yes The ID of the user who gets the role assigned.
rid yes The ID of the role which was assigned.
rname yes The fully qualified name of the role which was assigned.
Assigning a group to a role

Operation value: group_role.assigned

Properties:

Property Always present Description
gid yes The ID of the group which gets the role assigned.
gname yes The name of the group which was assigned.
rid yes The ID of the role which was assigned.
rname yes The fully qualified name of the role which was assigned.
Assigning a user to a group

Operation value: user_group.assigned

Properties:

Property Always present Description
uid yes The ID of the user who gets the group assigned.
gid yes The ID of the group which was assigned.
gname yes The name of the group which was assigned.
Assigning a role to a permission

Operation value: role_permission.assigned

Properties:

Property Always present Description
pid yes The ID of the permission which gets the role assigned.
pname yes The fully qualified name of the permission which was assigned.
rid yes The ID of the role which was assigned.
rname yes The fully qualified name of the role which was assigned.
Changing the parent group of a group

Operation value: group.updated

Properties:

Property Always present Description
gid yes The ID of the group which has been updated.
gname yes The name of the group which has been updated.
pgid yes The ID of the new parent group or an empty string if no parent group was assigned.
Unassign a user from a role

Operation value:  user_role.assigned

Properties:

Property Always present Description
uid yes The ID of the user who gets the role unassigned.
rid yes The ID of the role which was unassigned.
rname yes The fully qualified name of the role which was unassigned.
Unassign a group from a role

Operation value: group_role.unassigned

Properties:

Property Always present Description
gid yes The ID of the group which gets the role unassigned.
gname yes the name of the group which gets the role unassigned.
rid yes The ID of the role which was unassigned.
rname yes The fully qualified name of the role which was unassigned.
Unassign a user from a group

Operation value: user_group.unassigned

Properties:

Property Always present Description
uid yes The ID of the user who gets the group unassigned.
gid yes The ID of the group which was unassigned.
gname yes The name of the group which was unassigned.
Unassign a role from a permission

Operation value: role_permission.unassigned

Properties:

Property Always present Description
pid yes The ID of the permission which gets the role unassigned.
pname yes The fully qualified name of the permission which gets the role unassigned.
rid yes The ID of the role which was unassigned.
rname yes The fully qualified name of the role which was unassigned.

External User Management

Users originating from an external identity provider (e.g. OpenID Connect provider) can be managed in Bosch IoT Permissions in order to assign them to groups, roles, etc..
These users will be authenticated based on the credentials persisted in the external authentication provider.

External users are added to Bosch IoT Permissions individually, when they log in for the first time at our service.

They are identified with following icon . The Administrator UI will support you in creating and deleting assignments to other Bosch IoT Permissions entities.

For authentication purposes (i.e. token signature check) Bosch IoT Permissions accesses the external provider in some cases in real time. As a result, authentication will fail if the external provider is unavailable.

The currently supported OpenID Connect providers are described at Supported external identity providers.



Authentication and Authorization for Service API 2

The Service API 2 offers several ways for authentication and authorization. It is a full successor for all usage scenarios from Service API 1 related to authentication and authorization. It is therefore the recommended way to perform authentication and authorization via Service API 2.

Because Service API 2 does not yet support all use cases from Service API 1 there is sometimes the need to invoke resources from Service API 1. All resources of Service API 1 accept Authorization Tokens as a replacement for the Identity Context ID (see Identity Context) from Service API 1. See also the section Compatibility of Service API 1 and Service API 2 for more information.

All authentication possibilities are described in following sections:

JSON Web Token - JWT

Service API 2 of IoT Permissions utilizes JSON Web Tokens (JWTs) for authentication and authorization information exchange.

JWT is an open standard (RFC 7519) for passing information between applications (mostly web applications) and is also used for Single Sign On scenarios. Typically the kind of information which is contained in a JWT is the identity data of the authenticated user.

JWT relies on other JSON-based standards: JSON Web Signature (JWS) and JSON Web Encryption (JWE). JWE is currently not supported by IoT Permissions.

JSON objects which are contained in a token are called JWT Claims Set. A field of such a Claims Set is called a Claim which consists of a Claim Name and Claim Value (JSON property name and value). A JWT consists of three parts which are Base64 encoded and separated with a dot. These three parts are the token header, the token body and the signature of the token.

Detailed information about the JWT standard may be found at: RFC 7519 or jwt.io.

Benefits of using JWTs
Serverless "Is user authenticated?"-checks

Because JWTs are self-contained and signed, clients can check if the user is currently logged in by validating the signature of the token and checking the expiration date. This is possible without time consuming server calls. Only the public key of the server which signed the JWT is needed, but that public key can be requested once and can be cached for all subsequent validations.

Serverless access control checks

Similarly as with "Is user authenticated?"-checks, clients may perform access control checks by validating JWT tokens and checking that the token contains a required group, role or permission. No server calls are needed, hence the access control performance is very good. Only the public key of the server which signed the JWT is needed, but that public key can be requested once and can be cached for all subsequent validations.

Stateless identity server

Opposed to other authentication information exchange concepts (e.g. with session IDs), JWTs do not require server-side state. Because of that, the servers may provide better scalability, reliability and operability.

Small token size

JWTs are based on JSON which is a relatively compact data format. Additionally, clients may specify which claims should be included in the JWT when the token is created. Because of these two facts, the size of JWTs may be relatively small. This is a important benefit because of that they can be transmitted in HTTP cookie headers for Single-Sign-On purposes.

Usage of JWTs in IoT Permissions

Please see Usage of JWTs in IoT Permissions to get an overview which resources of IoT Permissions issue or consume JWTs.

Basic and Bearer Authentication

Service API 2 supports Basic authentication, by providing your username and password to a tenant specific authentication resource for creating an ID Token (see also JSON Web Token - JWT and Usage of JWTs in IoT Permissions).

Basic Authentication Example

Username: Admin
Password: Admin

String to be encoded: Admin:Admin

Resulting HTTP Header: Authorization: Basic QWRtaW46QWRtaW4=

The issued ID Token does not provide any authorization information. It defines that the user is authenticated and can be used to issue multiple Authorization Tokens at the authorization resource. Issuing an Authorization Token happens via providing a Bearer authentication.

Bearer Authentication Example

ID Token issued by the authentication resource: <header>.<payload>.<signature>

Resulting HTTP Header: Authorization: Bearer <header>.<payload>.<signature>

A Bearer authentication is also used when changing the initial password of a user.

Agent Credentials

An Agent Credential is a secret token which a user can generate for himself using the Service API 2. The user can give Agent Credentials to applications that should act on behalf of him, thus eliminating the need to authenticate via user name and password. While creating the Agent Credential the user defines a sub-set of his roles and permissions by defining the applications and scopes that should be bound to the Agent Credentials.

When managing Agent Credentials, keep the following concepts and restrictions in mind:

  • A user can define various Agent Credentials valid at the same time. It is possible to store a reference at the Agent Credentials to define the context where the Agent Credentials should be used for.
  • Agent Credentials are bound to the user that created them. Only this user is able to see or delete them.
  • While creating the Agent Credential the user defines a sub-set of his roles and permissions by defining the Agent Credentials Context. The Agent Credentials Context defines the applications and scopes that should be bound to the Agent Credentials. If the ID Token issued for an Agent Credential is used for issuing an Authorization Token, the Agent Credentials Context defines the default value for the applications and scopes parameters of the authorization resource. It is only possible to create an Authorization which contains a sub-set of this default values.
    Example: Let's assume an Agent Credential is defined with the applications IM and MY_APP. By this it is not possible to issue an Authorization Token with permissions and roles for the application MY_OTHER_APP but it is possible to issue an Authorization Token which contains roles and permissions for IM, MY_APP or both.
  • When creating Agent Credentials a password is provided in the response of the creation request. The user who created the Agent Credential is responsible to store the password. It is not possible to authenticate without the password.
  • The effective roles and permissions of an Agent Credential are determined when an Agent Credentials is used for authorization. This means, the issued Authorization Token which is loaded, only contains roles and permissions, or a subset of them, which are part of the Agent Credentials Context and which the user has at this point in time.
  • If the password of a user has expired, his Agent Credentials still work. They also keep working if the related User is locked.
    If the related User is deleted, his Agent Credentials also get deleted and cannot be used anymore for authentication and authorization.
  • An Agent Credential created by a privileged user is privileged as well. This means that it is possible to perform privileged operations using this Agent Credential (assign additional permissions, create privileged users, etc.). If this is not the desired behavior we suggest to use a non-privileged user to create an Agent Credential.

Because of this behavior Agent Credentials are "Refresh Tokens" and can be used for example for scenarios like a Remember Me functionality. See also Remember Me for further information.

Authentication and Authorization for Service API 1

All authentication possibilities are described in following sections:

Basic Authentication

Service API 1 supports Basic authentication, by providing your username and tenant name as part of the Basic Authentication username, separated by a backslash "\".

Username: <Tenant name>\<Username> 
Password: <Password>

Basic Authentication Example

Username: DEFAULT\Admin
Password: Admin

String to be encoded: DEFAULT\Admin:Admin

Resulting HTTP Header: Authorization: Basic REVGQVVMVFxBZG1pbjpBZG1pbg==

Basic Authentication is not recommended for an application which issues several consecutive requests to the Service API 1. Each request will create a new Identity Context session on the service side. It is recommended to request an Identity Context once and use the Identity Context ID for subsequent requests, as described in section Identity Context. This way the existing Identity Context session is reused on the service.

Identity Context

An Identity Context is an IM entity generated automatically after a successful authentication. The context ID should be used for accessing the Identity Context in further requests. The Identity Context can be seen like a session for the IM backend. This also means that the Identity Context will expire after a configurable amount of time.

Identity Context data

The Identity Context provides information about the user and the roles, permissions, groups, and so on, which are assigned to the user for whom the context was created. Applications which integrate with Identity Management will make authorization decisions based on this information. As the Identity Context is designed to perform authorization checks only, the contained entities do not provide localized attributes. If you are interested in the localized entities, which are contained in (or referenced from) the Identity Context, you must retrieve them separately.

Identity Context lifecycle
Creation

The Identity Context is created on an authentication call (based on user data, group and role assignments). It is returned as a result of a successful authentication. The Identity Context is stored by the Identity Management service and is is never modified after creation.

Examples:

Usage

After authentication the Identity Context is returned as a result. At least the Identity Context ID hat to be stored by the application. With this ID the application can issue IM API calls which need authentication. The ID can also be used to retrieve the Identity Context again from IM. The ID can also be passed to another service, so that this service can retrieve the Identity Context to get user and authorization information.

Examples:

Invalidation

The Identity Context is invalidated on user logout or by an explicit API call. To enforce a new login, the Identity Context gets invalid automatically when a pre-defined time has passed. By default the timeout is 120 minutes. The timeout can vary, as it can be specified by the application which implements user login. The maximum timeout value is 10 hours.

Identity Context Refresh Token

The purpose of an Identity Context Refresh Token is to provide a simple way of refreshing a session (Identity Context) without the necessity to hold the Basic Credentials of the user. 

An Identity Context Refresh Token can be created together with an Identity Context. Basic Credentials are used to create the initial Identity Context and Identity Context Refresh Token. After creation of the initial token it could be used to refresh the Identity Context as well as to create a new Identity Context Refresh Token. By using this technique it is possible to refresh a user session indefinitely.

The token has the same expiration as the created Identity Context and it will be invalidated when it gets refreshed by creating a new Identity Context with an Identity Context Refresh Token.

An example for creating and using an Identity Context Refresh Token could be found in Create an Identity Context Refresh Token using the Service API 1 and use it for Authentication.

API Key

An API Key is a secret token which a user can generate for himself using the Service API 1. The user can give the API Key to applications that should act on behalf of him, thus eliminating the need to authenticate via user name and password. While creating the API Key the user defines a sub-set of his roles and permissions that should be bound to the API Key.

When managing API Keys, keep the following concepts and restrictions in mind:

  • A user can define various API Keys valid at the same time, but their names must be unique per user.
  • API Keys are bounded to the user that created them (only this user is able to see or delete them).
  • While using an API Key for authentication, it is not possible to perform API Key related operations (e.g. show or create other API Keys).
  • The effective roles and permissions of an API Key are determined when an API Key is used to authenticate. This means, the Identity Context which is loaded, only contains roles and permissions which are part of the API Key (including permissions assigned to API Key roles) and which the user has at this point in time.
  • When an API Key contains a role the permissions assigned to this role will be part of the corresponding IdentityContext even if they are not specified in the API Key.
    This is useful for scenarios where you want to be able to change the contained permissions transparently.
  • Even though the password of the user who created an API key expires, the API Key of the user still works. Not even the locking state of a user has influence on the viability of his API Keys.
    However, deleting the user or one of the permissions related to the key will take effect immediately.
  • An API Key created by a privileged user is privileged as well. This means that it is possible to perform privileged operations using this API Key (assign additional permissions, create privileged users, etc.). If this is not the desired behavior we suggest to use a non-privileged user to create an API Key.

API Key example

Find an example in the section: Create an API-Key using the Service API 1.

Act on Behalf of Another Tenant

Bosch IoT Permissions provides the possibility for users to act on behalf of another tenant. This means that if a tenant offers permissions (e.g. to manage its users) with applicable scope PROVIDER, it is possible to switch the identity context to the providing tenant. In that case, users of a consuming tenant (granted with those permissions) are able to see, manipulate, and create data on behalf of the providing tenant (i.e. transparently act as if the user's entity would belong to the other tenant).

Example of the steps required in order to be able to act on behalf of another tenant:

  1. Get an Offering with applicable scope PROVIDER (via Tenant Relation)
  2. Authenticate yourself as a user known by IM using one of the following possibilities
    1. Basic authentication: the most common way is to authenticate with your user credentials (username and password)
    2. Using an API Key: a key created for a (technical) user that exists already
  3. Explicitly define the tenant you act on behalf of, i.e. authenticate:
    1. Using a Context ID: the Identity Context you got as authenticated user according to step 2
    2. and the Tenant ID of the providing tenant.
    This will create a new Identity Context to act on behalf of another tenant which contains a Context ID that you can use for all further requests while acting for that tenant.
    See our example for Using a Context ID for Authentication while using the Service API 1. The Context ID and Tenant ID must be given in the request's body part.
    See as well Create an Identity Context using the Service API 1 with an Act-On-Behalf-Of Authentication.
  4. Switch back to your old Identity Context
    As soon as you finish acting on behalf of another tenant you will be able to get your original identity context back.
    While using the UI, the session timeout for the old context will not count the time you are acting on behalf of the other tenant.

Restrictions

Acting on behalf of another tenant cannot be used nested. 

Tracing

Bosch IoT Permissions supports Tracing which helps analysing request flows and finding error causes. To accomplish that, a Trace ID (also known as "Correlation ID") is transferred between all HTTP calls which belong to a single operation flow. For all log entries of all layers (your application, reverse proxies, Bosch IoT Permissions' applications), the Trace ID is included to allow operators to correlate the log entries of the different applications. To analyse a single operation flow, all log entries with the respective Trace ID are collected.

Bosch IoT Permissions adheres to the https://zipkin.io/ tracing specification which is also supported by the Cloud Foundry Gorouter (see https://docs.pivotal.io/pivotalcf/2-0/concepts/http-routing.html#zipkin-headers).

Supplying tracing parameters to Bosch IoT Permissions

You can supply tracing parameters as HTTP headers to Bosch IoT Permissions when you invoke HTTP endpoints. If no tracing parameters are supplied, Bosch IoT Permissions generates them internally.

The following tracing parameters are supported by Bosch IoT Permissions according to https://github.com/openzipkin/b3-propagation#overall-process

  • X-B3-TraceId
  • X-B3-SpanId
  • X-B3-ParentSpanId

Receiving tracing parameters from Bosch IoT Permissions

Bosch IoT Permissions supplies the Trace ID (which has been used for the request) in the response either as an HTTP header named trace-id

or included in the message (for error responses).

If problems occur, this Trace ID can be given to the Bosch IoT Permissions Service operators for error analysis purposes.

API Description

In order to beneficiate of the Bosch IoT Permissions functionality in your projects you can either send RESTful HTTP requests directly to the service (i.e. use the Service API 1 or Service API 2), or integrate one of our clients, which expose the API in a convenient way, into your business applications.

The REST architectural style with a client, that initiates requests, and the server to process those requests and to return appropriate responses, is optimal to offer the Bosch IoT Permissions functionality as a remote Web service, and thus to design networked applications.

Service Interface Stability

The Bosch IoT Permissions functionality is exposed via RESTful HTTP resources also know as interfaces. Some of these interfaces and their functionality implement a standard and are very stable. Others are specific to the Bosch IoT Permissions service and have to evolve till they are declared as a stable functionality. All functionalities are therefore marked with their stability level. A change of a stability level will always be published in service update notes.

  • Stable: This functionality is to undergo only backwards-compatible changes. This means that service requests and responses are able to be extended with additional content. Additive changes like adding a new field to an existing data structure or adding a new functionality do not force changes on the components that do not use the new field or functionality. Error codes used in error responses might be extended with new codes to be able to provide new functionality especially regarding new security features.
  • Beta: Functionality with this stability level evolve till they reach the Stable level. Evolve means that the interface could be declared as Stable without any change, could be be changed in backwards-incompatible ways, or could be removed without declaring it as Deprecated.
  • Deprecated: This functionality will be removed in a future service release. There is a period of at least one year between declaring the functionality as Deprecated and their removal. 

Client Stability and Versioning

The Bosch IoT Permissions service provides programming libraries as clients for the Bosch IoT Permissions service. These clients evolve continuously with the service interfaces to take usage of new functionality. A client interface or operation is stable, if it is not marked as beta. If an operation which is marked as beta creates objects from classes which are not already used by other stable API operations, these classes are also beta as they are only accessible by beta code.

A semantic-versioning scheme (Major.Minor) is used, to provide information on client API compatibility between versions:

  • Major: A major release may include incompatible changes to interfaces marked as deprecated. A major release may additionally include the changes described for a minor release.
  • Minor: A minor release includes backwards-compatible changes to stable interfaces and bugfixes. Stable interfaces might be declared as deprecated. Beta interfaces might be added, changed in an incompatible way or removed. We kindly request your feedback on Beta interfaces, so that they can be improved and promoted to stable.
  • Beta (version contains "beta"): In a beta version all operations are in beta state and subject to change.

Note: The semantic version of "API 1 Client for Java" is the schema version of im.xsd, not the artifact version. It is included in the jar in im-jaxrs-common.

Client Deprecation Policy

Functionality in the client can be declared as deprecated with a minor release. Six months after that declaration, the functionality may be removed with a major version. Only the latest major version will receive minor updates. Previous major versions will not be maintained. If you need the six-months period to be extended for specific deprecated functionality, please contact us.

We recommend to update to the latest client version early, so that you can participate in bug fixes and new features. You may use your IDE or a code quality scanner, to be warned when you are using deprecated functionality. In this case you need to update the client version within the six months, to ensure compatibility with your code.

Service Interfaces

Find a detailed description of the interfaces in the following sections:

Service API 1

The Service API 1 is exposed at URL: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

The Service API 1 is a RESTful remote API for Bosch IoT Permissions entities.

The Service API 1:

  • is XML-based
  • has Atom-Feed semantics
  • is self-describing (in hypermedia REST HATEOAS style)
  • provides CRUD operations on IM entities, I18NAttributes, relations and configurations (e.g. external data provider setup)
  • provides authentication resources
  • supports filtering, sorting and attribute selection

For all types of entities that exist in Bosch IoT Permissions there is a corresponding REST resource available via the Service API 1.
There is e.g. a REST resource for the entity user which allows to list existing users, to create new ones or to delete them.

For all relations between entities that exist in Bosch IoT Permissions there is a corresponding REST relation resource available via the Service API 1.
The relation resources allow to create or remove the assignment between the two involved entities.
Adding an user to a group is e.g. done by creating an assignment between the user and the group.

In addition there are some special resources in the Service API 1 like the authentication resource which can e.g. be used to retrieve the IdentityContext for given credentials.

The user performing the request must have permissions as defined in the relation description.
This means that e.g. a list request to a resource returns only entities for which the user has read permission.

All resources and functionality have Service Interface Stability level "Stable" except the functionality is explicitly declared with another stability level.

On a HTTP GET request to the Bosch IoT Permissions root context the developer receives a list of links to the central functionality of the Service API 1.

Network compression

The whole Service API 1 can be used with enabled network traffic compression. To enable compression it is necessary to attach the HTTP header "Accept-Encoding" with a value of "gzip". When accessing the Service API 1 via a Web browser, most browsers will attach this header automatically. You don't have to worry about that the response contains the header "Content-Encoding" with a value of "gzip".

Service API 1 - Features

  • Model for organizational elements
    • Tenant
    • User
    • Group / Sub-Group
    • Role
  • Model for infrastructure elements
    • Domain
    • Application
    • Permission
    • Role
  • Model for tenant relation elements
    • Offering
    • Tenant Relation
  • User Management
    • Users organized in (hierarchical) groups
    • Roles assigned to users/groups
    • Privileged user accounts
  • Application Management
    • Applications organized in domains
    • Applications defining permissions and roles
    • Permissions exposed for assignment to roles
  • Tenant Management
    • Logical separation of data between tenants
    • Empowerment for tenant administrators to manage the tenant's own elements
  • Tenant Relation Management
    • Well-defined data and service sharing between tenants
    • Offering permissions/roles to be used by other tenants
    • Managing relationships between tenants
    • Possibility for users of one tenant to act on behalf of another tenant
    • Possibility to limit tenant relations in time and scope
  • Services
    • Service API 1 is an XML based RESTful HTTP API (XML schema provided)
    • Authentication service for users:
      • Basic authentication (user credentials)
      • API key
      • Identity context ID (IM session token)
      • Act on behalf of another tenant
    • Authorization service for applications:
      • Manage applications permissions and roles by API
      • Check permissions and roles of authenticated user
    • Services to provide user self-service
      • User self-registration with email based activation
      • Manage own user data
      • Change forgotten password with a reset link sent by email
      • Email template mechanism
    • Service to manage the Client Access Tokens
    • JSON-based API to support your JavaScript-Only/No-backend application
      • Allows custom JS applications to take part in the single-sign-on mechanism.
      • JavaScript Support REST API expands Service API 1
      • Subset of Service API 1 functionality: Authentication resources, resources for validating and changing the password  
    • Internationalization (I18N) of names and descriptions for all IM elements
    • Safekeeping through mechanism to mark entities as deleted / data privacy protection through mechanism to permanently delete entities

XSDs

As the Service API 1 uses XML for request and response messages, the elements and data types are described in the following XSDs:

  • atom.xsd: The namespace prefix in the API is atom.
  • im.xsd: The namespace prefix in the API is im.

Find the XML schema files at https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/schema.html.

REST Resources overview

Root Resource - Index

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

General Description

Returns a list of links to the root services of the IM API

REST URI*

GET /

Body Type

none

Return Type

atom:linklist (see atom.xsd)

Required Permissions none

Failure Description

none

As the IM Server comes with default tenant, user etc. you should receive at least following links as a response.

<ns2:imResources>
 <link href=
        "https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/apikeys"
       rel="http://www.bosch.com/iap/im/apikey/create"/>
 // etc. etc.
 <link href=
        "https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users"
       rel="http://www.bosch.com/iap/im/user/list"/>
 <link href=
        "https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/"
       rel="self"/>
</ns2:imResources>

The response itself contains the <link... /> xml tags. These links help to navigate through the entity resource tree and show the hypermedia semantics of the IM API.

Tenant Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Tenant - list

General Description

Returns all tenants matching the given filter the current authenticated user has read permission on.

Method 

GET

Example URI

/tenants?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:tenant (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT

Failure Description

400 Bad Request 

The predicate filter is invalid 

401 Unauthorized 

The user is not logged in.

Tenant - create

Hint: This method should no longer be used. Use the Tenant Registration Resource instead which provides more options, especially the option to create FULL_SERVICE tenants.

General Description

Creates a tenant described by xml body.

Leading and trailing white spaces will be removed from the password.

Method 

POST 

Example URI

/tenants

Body Type

im:tenantCreation (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenant (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_TENANT

Failure Description

400 Bad Request 

The password could not be validated or mandatory information is missing in the XML body.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized 

The current authenticated user is not permitted to create a tenant.

409 Conflict

A tenant with the same name already exists.

Tip: Find an example for the XML body required at Create a tenant using the Service API 1.

Tenant - read

General Description

Returns more details about the tenant.

Method 

GET 

Example URI

/tenants/<tenantId>

Body Type

none

Return Type

im:tenant (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT

Failure Description

401 Unauthorized 

The current authenticated user is not permitted to read the tenant.

404 Not Found 

No matching tenant exists within IM.

Tenant - update

General Description

Updates the tenant as described by xml body.

Method 

PUT

Example URI

/tenants/<tenantId>

Body Type

im:tenant (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenant (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_TENANT

Failure Description

401 Unauthorized 

The current authenticated user is not permitted to read the tenant.

404 Not Found 

No matching tenant exists within IM.

Tenant - delete

General Description

Deletes the tenant.

Method 

DELETE 

Example URI

/tenants/<tenantId>

Parameter (Optional)

?permanently=true to erase the tenant instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions DELETE_TENANT or
ERASE_TENANT to delete permanently

Failure Description

401 Unauthorized 

The current authenticated user is not permitted to read the tenant.

404 Not Found

No matching tenant exists within IM.

Tenant - restore

General Description

Restores a deleted tenant.

Leading and trailing white spaces will be removed from the password.

Method

POST

Example URI

/tenants/<tenantId>

Body Type

im:user (see im.xsd)
(Hint: The tenantId field will be ignored, and though it can be omitted.)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenant (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_TENANT

Failure Description

400 Bad Request

The password could not be validated or mandatory information is missing in the XML body.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized

The current authenticated user is not permitted to restore the tenant.

404 Not Found

No matching tenant exists within IM or the tenant is not deleted.

409 Conflict

The tenant could not be restored because the tenant it belongs to is deleted.


Tenant - i18n attributes

General Description

Returns all i18n attributes of the specified tenant.

Method 

GET

Example URI

/tenants/<tenantId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT

Failure Description

401 Unauthorized 

The current authenticated user is not permitted to read tenants

404 Not Found 

No matching tenant exists within IM.

Tenant - email template - list

General Description

Returns all email templates for the specified tenant.

This resource doesn't support any query parameters. Query parameters for paging and sorting are ignored.

Method 

GET

Example URI

/tenants/<tenantId>/emailtemplates

Body Type none
Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type im:emailTemplate (see im.xsd)
Entry Content Media-Type application/vnd.bosch-com.im+xml
Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.

Tenant - email template - create

General Description

Creates a new email template of the given type for the specified tenant.

If the content of the email template is null or empty, no email template will be stored and a potentially existing email template will be deleted.

When a new email template is created, the respective functionality is enabled in the self-service settings of the tenant.

Method

POST

Example URI

/tenants/<tenantId>/emailtemplates/<type>

Supported <type> values:

  • ACTIVATION - such an email will be sent to a self-registered user to activate his user account
  • PASSWORD_RESET - such an email will be sent to a user whenever he requests a password reset
  • EMAIL_UPDATE - such an email will be sent to a user whenever he requests an update of his email address with verification
Body Type im:emailTemplateContent (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

400 Bad Request 

Mandatory information is missing in the XML body.

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.

Tip: Find details on how to compose your email template (grammar, placeholder, etc.) at Email Template Syntax.

Tip: Find an example for the XML body required at Create a new email template using the Service API 1.


Tenant - email template - update

General Description

Updates the persistent email template of the given type for the specified tenant.

If the content of the email template is null or empty, a potentially existing email template will be deleted.

Method 

POST

Example URI

/tenants/<tenantId>/emailtemplates/<type>

Supported <type> values:

  • ACTIVATION - such an email will be sent to a self-registered user to activate his user account
  • PASSWORD_RESET - such an email will be sent to a user whenever he requests a password reset
  • EMAIL_UPDATE - such an email will be sent to a user whenever he requests an update of his email address with verification
Body Type im:emailTemplateContent (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

400 Bad Request 

Mandatory information is missing in the XML body.

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.

Tenant - email template - read

General Description

Returns the email template of the given type for the specified tenant.

Method 

GET

Example URI

/tenants/<tenantId>/emailtemplates/<type>

Supported <type> values:

  • ACTIVATION - such an email will be sent to a self-registered user to activate his user account
  • PASSWORD_RESET - such an email will be sent to a user whenever he requests a password reset
  • EMAIL_UPDATE - such an email will be sent to a user whenever he requests an update of his email address with verification

Body Type

none

Return Type

im:emailTemplate (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.

404 Not Found

No matching email template exists within IM.

Tenant - email template - delete

General Description

Deletes the email template of the given type for the specified tenant.

When a new email template is deleted, the respective functionality is disabled in the self-service settings of the tenant.

Method

DELETE

Example URI

/tenants/<tenantId>/emailtemplates/<type>

Supported <type> values:

  • ACTIVATION - such an email will be sent to a self-registered user to activate his user account
  • PASSWORD_RESET - such an email will be sent to a user whenever he requests a password reset
  • EMAIL_UPDATE - such an email will be sent to a user whenever he requests an update of his email address with verification

Body Type

none

Return Type

none

Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.

404 Not Found

No matching email template exists within IM.

Tenant - email template - reset

General Description

Resets the email template of the given type to its default version for the specified tenant.

Method 

POST

Example URI

/tenants/<tenantId>/emailtemplates/<type>

Supported <type> values:

  • ACTIVATION - such an email will be sent to a self-registered user to activate his user account
  • PASSWORD_RESET - such an email will be sent to a user whenever he requests a password reset
  • EMAIL_UPDATE - such an email will be sent to a user whenever he requests an update of his email address with verification
Body Type none

Body Media-Type

none

Return Type

none

Required Permissions EMAIL_TEMPLATE_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate email templates.


Tenant - tenant settings - persist

General Description

Creates or updates settings of the specified type for the specified tenant.

Method

PUT

Example URI

/tenants/<tenantId>/tenantsettings/<type>

Supported <type> values:

PASSWORD - password related settings

SELF_SERVICE - self-service related settings

IDENTITY_PROVIDERS - identity providers related settings

Body Type im:tenantConfigSettings (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions TENANT_SECURITY_ADMINISTRATION

Failure Description

400 Bad Request

Mandatory information is missing in the XML body or the specified settings are not valid.

If the settings validation fails an InvalidPasswordConfigurationException will be thrown which contains further details regarding the invalid settings.

401 Unauthorized

The current authenticated user is not permitted to administrate tenant-specific settings.

It may take up to 10 minutes before changes to the tenant-specific settings will become active on all instances.  

Tip: Find an example for the XML body required at Create and update tenant-specific settings using the Service API 1 .

Tenant - tenant settings - read

General Description

Returns the settings of the specified type for the specified tenant.

Method 

GET

Example URI

/tenants/<tenantId>/tenantsettings/<type>

Supported <type> values:

PASSWORD - password related settings

SELF_SERVICE - self-service related settings

IDENTITY_PROVIDERS - identity providers related settings    

Parameter (Optional)

?showEffective=true to get the effective settings instead of the persisted settings.

The persisted settings are the settings which were specified and persisted for the given tenant.

The effective settings are the settings which are used for the given tenant (e.g. the global default settings if no settings were persisted for the given tenant).

Body Type

none

Return Type

im:tenantSettings (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions TENANT_SECURITY_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate tenant-specific settings.

404 Not Found

No matching tenant-specific settings exist within IM.

Tenant - tenant settings - delete

General Description

Deletes the settings of the specified type for the specified tenant.

When deleting tenant-specific password settings the default password settings become active again.

Method

DELETE

Example URI

/tenants/<tenantId>/tenantsettings/<type>

Supported <type> values:

PASSWORD - password related settings

SELF_SERVICE - self-service related settings

IDENTITY_PROVIDERS - identity providers related settings    

Body Type

none

Return Type

none

Required Permissions TENANT_SECURITY_ADMINISTRATION

Failure Description

401 Unauthorized

The current authenticated user is not permitted to administrate tenant-specific settings.

404 Not Found

No matching tenant-specific settings exist within IM.

It may take up to 10 minutes before changes to the tenant-specific settings will become active on all instances.  

Password related settings

Setting all password related properties is optional. Specifying off as the value will deactivate the property.

When persisting password related properties using the tenant settings resource, the configuration type PASSWORD must be used.

Attribute

Configuration property

Default value

Maximum value

Description

Upper-case characters

im_password_chars_
upperCase

1

100

The minimum number of upper-case characters in a password (characters [A-Z]).

im_password_chars_
upperCaseForPrivilegedUsers
1 100 Same as im_password_chars_upperCase but for privileged users.

Digits

im_password_chars_
digits

1

100

The minimum number of digits in a password (characters [0-9]).

im_password_chars_
digitsForPrivilegedUsers
1 100 Same as im_password_chars_digits but for privileged users.
Special characters im_password_chars_
special
1 100 The minimum number of special characters in a password (all characters except [a-zA-Z_0-9]).
im_password_chars_
specialForPrivilegedUsers
1 100 Same as im_password_chars_special but for privileged users.
Allow white space characters im_password_chars_
allowWhitespace
true

Definition whether white space characters are allowed in a password (white space character is [\s]).

The value off will disable validating the given password with this rule, thus allowing to define white spaces within a password.

Leading and trailing white spaces will always be removed before the password will be used for validation or authentication.

im_password_chars_
allowWhitespaceForPrivilegedUsers
true
Same as im_password_chars_allowWhitespace but for privileged users.

Maximum character repetition

im_password_chars_
maxRepetition

off

100

The number of repetitions of the same character within a password.
(The value off will disable validating the given password with this rule, thus infinite repetitions are allowed.)

im_password_chars_
maxRepetitionForPrivilegedUsers

2

100 Same as im_password_chars_maxRepetition but for privileged users.

Minimum password length

im_password_length_
min
8 100 The minimum number of characters in a password (value must be 5 or higher).
im_password_length_
minForPrivilegedUsers
10 100 Same as im_password_length_min but for privileged users.

Days until password expires

im_password_expiration_
days
off 1000

The number of days a password is valid.
(The value off will disable validating the given password with this rule, thus the password never expires.)
A password expires after the number of days defined using this property.
Activating this check would require to adapt as well the length of the password history (see im_password_history_length), if you need to prevent that a user tries to reuse an old password.

im_password_expiration_
daysForPrivilegedUsers
off 1000 Same as im_password_expiration_days but for privileged users.
Enforce initial password change im_password_
changeAtLogin
true

Definition whether the system will force a user to change his password after his first successful authentication.

im_password_
changeAtLoginForPrivilegedUsers
true
Same as im_password_changeAtLogin but for privileged users.
Password changes per day im_password_change_
maxPerDay
10 100

The number of allowed password changes (100 at the maximum) per day (last 24 hours).

im_password_change_
maxPerDayForPrivilegedUsers
10 100 Same as im_password_change_maxPerDay but for privileged users.
Password history im_password_history_
length
10 100

The number of old passwords (resulting from password changes executed so far) that are to be stored, if you need to prevent that a user tries to reuse an old password (100 at the maximum).

im_password_history_
lengthForPrivilegedUsers
100 100 Same as im_password_history_length but for privileged users.
Failed login attempts before raising wait time im_password_
failedLoginsBeforeWait
3 100

The number of failed login attempts (increased on failed authentication and password change attempts) before enforcing a wait time for login attempts.

The values off and 0 will disable the functionality.

External users will also be affected by this functionality.

im_password_
failedLoginsBeforeWait
ForPrivilegedUsers
3 100 Same as im_password_failedLoginsBeforeWait but for privileged users.
Additional wait time per failed login im_password_
failedLoginsRaisingWaitTime
5 100

Defines the additional wait time (in seconds) per additional failed login.

This setting has no effect if im_password_failedLoginsBeforeWait is disabled.

im_password_
failedLoginsRaisingWait
TimeForPrivilegedUsers
5 100 Same as im_password_failedLoginsRaisingWaitTime but for privileged users.

Failed login attempts before locking user

im_password_
failedLoginsBefore
LockingUser
50 100

The number of failed login attempts (increased on failed authentication and password change attempts) before a user is "locked" (100 at the maximum).

The counter of failed login attempts is reset to 0 after a successful authentication.

External users will never be "locked" by IM.

im_password_
failedLoginsBeforeLocking
UserForPrivilegedUsers
50 100 Same as im_password_failedLoginsBeforeLockingUser but for privileged users.




Self-service related settings

Setting all self-service related properties is optional.

When persisting self-service related properties using the tenant settings resource, the configuration type SELF_SERVICE must be used.

Attribute

Configuration property

Default value

Maximum value

Description

User self-registration enabled im_selfservice_user_registration_enabled true   Specifies whether the user self-registration functionality is enabled or not.

User activation code timeout

im_code_timeout_activation

1440

43200

Defines the timeout (in minutes) for the code provided to self-registered users to activate their user account.
The value that can be assigned must be between 1 and 43200 (30 days).

Password reset enabled im_selfservice_password_reset_enabled true   Specifies whether the password reset functionality is enabled or not.
Password reset code timeout im_code_timeout_passwordReset 30 43200 Defines the timeout (in minutes) for the code provided for user self-service to reset the old password and define a new password.
The value that can be assigned must be between 1 and 43200 (30 days).
Email address update with verification im_selfservice_verified_email_update_enabled true   Specifies whether the verified email update functionality is enabled or not.

Email address update with verification code timeout

im_code_timeout_emailUpdate

1440

43200

Defines the timeout (in minutes) for the code provided for user self-service to confirm the update of the email address associated to their user account.

The value that can be assigned must be between 1 and 43200 (30 days).

Identity Providers related settings

Setting all identity providers related properties is optional.

When persisting identity providers related properties using the tenant settings resource, the configuration type IDENTITY_PROVIDERS must be used.

Attribute

Configuration property

Default value

Description

Display Login with CIAM on service UI im_service_ui_login_with_ciam_enabled true Specifies whether a login dialog for a login via a Bosch Account is displayed on the Bosch IoT Permissions service UI login screen.

Display Login with Google on service UI

im_service_ui_login_with_google_enabled

false

Specifies whether a login dialog for a login via a Google Account is displayed on the Bosch IoT Permissions service UI login screen.

Accepted CIAM client IDs im_accepted_ciam_clientids   Specifies the accepted client IDs in the audience claim of a Bosch ID token. Multiple client ID could be given by separating them with a comma.
Accepted Google client IDs im_accepted_google_clientids   Specifies the accepted client IDs in the audience claim of a Google ID token. Multiple client ID could be given by separating them with a comma.
Tenant Registration Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

The Tenant Registration Resource allows to create a tenant with all needed supplementary entities with just one REST request.

This includes:

  • The creation of the tenant itself
  • The creation of the initial administrative user
  • The assignment of the service administrator role for the administrative user

The request also has some additional options:

  • With element createApiKey an API Key for the initial user can be created. The API key includes the service administrator role.
  • With element userEmail an email address can be set for the initial user.
  • With element userSpecifiedPassword the enforced password change on first login can be disabled.

The execution of this request is protected by the permission "CREATE_TENANT".

Tenant registration - create

General Description

Registers a tenant described by the XML body.

Method

POST

Example URI

/tenantregistration

Body Type

im:tenantRegistrationCreation (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenantRegistration (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_TENANT

Failure Description

400 Bad Request
The password could not be validated or mandatory information is missing in the XML body.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized
The current authenticated user is not permitted to create a tenant.

409 Conflict
A tenant with the same name already exists.

Tip: Find an example for the XML body required at Register a complete tenant using the IM REST API.

The type of tenant to create is optional.
In case your request body does not specify a creationType, the new tenant will be of type DEFAULT.
However, in case the tenant was created within the Cloud Foundry Marketplace, the tenant will be of type FULL_SERVICE.

  • DEFAULT means the tenant has no privileges to administrate any sub-tenants. The IM offering contains the IM Tenant Administrator role, and this role is automatically assigned to the initial user of this tenant. 
  • FULL_SERVICE means the tenant may create sub-tenants. The IM offering contains the IM Service Administrator role, and this role is automatically assigned to the initial user of this tenant. 
User Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

User - list

General Description

Returns all users matching the given filter the current authenticated user has read permission on.

Method

GET

Example URI

/users?query=<predicateFilter>
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:user (see im.xsd) - without the password element

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_USER

Failure Description

400 Bad Request
The predicate filter is invalid.

401 Unauthorized
The current authenticated user is not permitted to read users.

User - create

General Description

Creates a user as described by xml body.

Leading and trailing white spaces will be removed from the password.

Method

POST

Example URI

/users

Body Type

im:user (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:user (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_USER

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body or the password could not be validated.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized
The current authenticated user is not permitted to create a user.

If a non-privileged user is trying to create a privileged user an IllegalUserModificationException will be thrown. For detailed information see Privileged Users.

409 Conflict
A user with the same name already exists.

Tip: Find an example for the XML body required at Create a user using the Service API 1.

User - read

General Description

Returns more details about the user.

Method

GET

Example URI

/users/<userId>

Body Type

none

Return Type

im:user (see im.xsd) - without the password element

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user exists within IM.

User - update

General Description

Updates the user as described in the XML body.

Leading and trailing white spaces will be removed from the password.

Method

PUT

Example URI

/users/<userId>

Body Type

im:user (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:user (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

400 Bad Request
The password validation fails, or the user is managed in an external system and cannot be updated within IM.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized
The current authenticated user is not permitted to update the user.

If a non-privileged user is trying to update a privileged user an IllegalUserModificationException will be thrown. For detailed information see Privileged Users.

404 Not Found
No matching user exists within IM.

User - delete

General Description

Deletes or erases the user.

Method

DELETE

Example URI

/users/<userId>

Parameter (Optional)

?permanently=true to erase the user instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions
  • In case of delete:

    • DELETE_USER or

    • SELF_DELETE_USER if the specified userId is the ID of the own user account

  • In case of erase: ERASE_USER

Failure Description

400 Bad Request
The user is managed in an external system and cannot be deleted within IM.

401 Unauthorized
The current authenticated user is not permitted to delete the user.

If a non-privileged user is trying to delete or erase a privileged user an IllegalUserModificationException will be thrown. For detailed information see Privileged Users.

404 Not Found
No matching user exists within IM.

User - restore

General Description

Restores a deleted user.

Method

POST

Example URI

/users/<userId>

Body Type

none

Return Type

im:user (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_USER

Failure Description

400 Bad Request
The user is managed in an external system and cannot be modified within IM.

401 Unauthorized
The current authenticated user is not permitted to restore the user.

If a non-privileged user is trying to restore a privileged user an IllegalUserModificationException will be thrown. For detailed information see Privileged Users.

404 Not Found
No matching user exists within IM or the user is not deleted.

409 Conflict
The user could not be restored because the tenant it belongs to is deleted.

User - i18n attributes

General Description

Returns all i18n attributes of the specified user.

Method

GET

Example URI

/users/<userId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read users

404 Not Found 
No matching user exists within IM.

User - list user attributes

General Description

Returns all attributes of the user with the given ID.

Method

GET

Example URI

/users/<userId>/userattributes

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:userAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user exists within IM.

User - create user attribute

General Description

Creates a user attribute as described in the XML body.

Method

POST

Example URI

/users/<userId>/userattributes

Body Type

im:userAttribute (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:userAttribute (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized
The current authenticated user is not permitted to update the user.

409 Conflict
A user attribute with the same key already exists for this user.

Tip: Find an example for the XML body required at Create an User Attribute using the Service API 1.

User - read user attribute

General Description

Returns the user attribute for the given key.

Method

GET

Example URI

/users/<userId>/userattributes/<attributeKey>

  • The attributeKey is the identifier of the user attribute (see type im:userAttributeType)
  • If the attributeKey contains special characters like white spaces, a semicolon and so on, then it must be URL encoded.

Body Type

none

Return Type

im:userAttribute (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user attribute exists within IM.

User - update user attribute

General Description

Updates the user attribute as described in the XML body.

Method

PUT

Example URI

The Resource is accessible under the following endpoints:

  • /users/<userId>/userattributes
  • /users/<userId>/userattributes/<attributeKey>
    • The attributeKey is the identifier of the user attribute (see type im:userAttributeType)
    • If the attributeKey contains special characters like white spaces, a semicolon and so on, then it must be URL encoded

Body Type

im:userAttribute (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:userAttribute (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to update the user.

404 Not Found
No matching user attribute exists within IM.

User - delete user attribute

General Description

Deletes the user attribute.

Method

DELETE

Example URI

/users/<userId>/userattributes/<attributeKey>
  • The attributeKey is the identifier of the user attribute (see type im:userAttributeType)
  • If the attributeKey contains special characters like white spaces, a semicolon and so on, then it must be URL encoded

Body Type

none

Return Type

none

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to update the user.

404 Not Found
No matching user attribute exists within IM.

User - persist user attributes

General Description

Persist a list of user attributes.

Potentially existing user attributes with the same key will be overwritten.

Method

PUT

Example URI

/users/<userId>/userattributes

Body Type

im:userAttributes (see im.xsd)

Return Type

none

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to update the user.

Tip: Find an example for the XML body required at Create or update multiple User Attributes using the Service API 1

User - list user profile attributes
General Description Returns all attributes supported by the IM user profile of the user with the given ID.
Method GET
Example URI /users/<userId>/userprofile
Body Type none
Return Type im:userProfile (see im.xsd)
Return Media-Type application/vnd.bosch-com.im+xml
Required Permissions READ_USER or none if the specified userId is the ID of the own user account
Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user exists within IM.

Tip: Find an example for such a request at Query User Profile attributes.

User - list assigned groups

General Description

Returns a list of all groups the user is assigned to.

Method

GET

Example URI

/users/<userId>/groups

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:group (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP and READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user exists within IM.

User - list assigned roles

General Description

Returns a list of all roles the user is assigned to.

Method

GET

Example URI

/users/<userId>/roles

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE and READ_USER or none if the specified userId is the ID of the own user account

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read the user.

404 Not Found
No matching user exists within IM.

User - update email address with verification

General Description

Updates the email address of the user as described in the XML body.

As part of the update process an email is sent to the new email address in order to verify that the email address is valid and that it belongs to the user. The email contains an activation link, which will be valid for 180 minutes by default. The validity duration can be specified per tenant using the tenant settings resource.

The content of the email must be specified using the related email template (EMAIL_UPDATE).
The email can be send only in case the email template exists for the tenant of the user.

The "update email address with verification" functionality can be enabled and disabled via the tenant settings resource.

The activation of the email address is triggered via User - activate email address.

Method

POST

Example URI

/users/<userId>/updateemailaddress

Body Type

im:updateEmailAddress (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions UPDATE_USER or none if the specified userId is the ID of the own user account

Failure Description

400 Bad Request
Mandatory information is missing in the XML body
or the email could not be sent (e.g. because of missing email address or invalid email template),
or the user is managed in an external system and cannot be updated within IM,
or the user is inactive or locked and is therefore not allowed to update the email address,
or verfied email update is not enabled in the self service tenant settings.

401 Unauthorized
The current authenticated user is not permitted to update the email address of the user.

If a non-privileged user is trying to update a privileged user an IllegalUserModificationException will be thrown. For detailed information see Privileged Users.

404 Not Found
No matching user exists within IM.

Tip: Find an example for the XML body required at Update email address with verification using the Service API 1.

User - activate email address

General Description

Activates an email address update which was triggered via User - update email address with verification by providing the secret activation code.

Afterwards the email address of the user will be replaced with the new one.

In order to prevent brute-force attacks the activation code of the user will be cleared when an incorrect activation code is provided.

This resource can be used without authentication.

Method

POST

Example URI

/users/<userId>/activateemailaddress/<activationcode>

Body Type

none

Return Type none
Required Permissions none

Failure Description

400 Bad Request
The provided activation code has expired or isn't correct.

404 Not Found 
No matching user exists within IM.

Tip: Find an example of the request at Activate new email address using the Service API 1.

Self Registered User Resource

User self-registration is designed to be processed in multiple steps. See User self-registration for conceptual details.

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Self Registered User - create

General Description

Creates a user which provided the user data himself.

Leading and trailing white spaces will be removed from the password. 

This resource can be used without authentication.

The "User self-registration" functionality can be enabled and disabled via tenant settings (see Tenant Resource).

It is not possible to create a privileged user by self registration.

Self-registrered users which were not activated within 30 days are automatically deleted.

Method

POST

Example URI

/selfregisteredusers

Body Type

im:selfRegisteredUser

Body Media-Type application/vnd.bosch-com.im+xml

Return Type

im:user (see im.xsd)

Return Media-Type application/vnd.bosch-com.im+xml
Required Permissions none

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body or the password is not valid according to the settings defined at the IM server.

Or user self-registration is not enabled in the self service tenant settings.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized
The creation of a privileged user by self registration is forbidden.

409 Conflict
A user with the same name already exists.

Tip: Find an example for the XML body required at Create a self-registered user using the Service API 1.

Self Registered User - activation email

General Description

Sends an email with an activation link to a user which was created via self-registration service, and which is not active yet.

The content of the email must be specified using the related email template (ACTIVATION).
The email can be send only in case the email template exists for the tenant of the user, the server's email configuration properties are set and an email address was persisted for the user.

The email contains a link with an activation code, which will be valid for three hours by default. The validity duration can be specified per tenant using tenant settings (see Tenant Resource).

Multiple requests to the same resource will trigger the server to send multiple emails with a different activation code.

Please note that self-registered users which were not activated within 30 days are automatically deleted. Activation emails cannot be sent after these 30 days have passed.

The activation of the user is triggered via Self Registered User - activate.

This resource can be used with and without authentication.

  • All users are allowed to send an activation email multiple times as long as the currently used activation code is expired.
  • Authenticated users which also provide the UPDATE_USER permission are allowed to send an activation email multiple times no matter of the expiration status of the currently used code.

Method

POST

Example URI

/selfregisteredusers/<userId>/activationemail

Body Type

none

Return Type

none

Required Permissions none

Failure Description

400 Bad Request
The user has no unexpired activation code or
the email could not be send (e.g. because of missing email address or invalid email template).

404 Not Found
No matching user exists within IM.

401 Unauthorized  
The authenticated user does not provide the UPDATE_USER permission or
the activation code of the un-authenticated user is not expired.

Tip: Find an example at Send an activation email using the Service API 1.

Self Registered User - activate

General Description

Activates a self-registered user by providing a secret activation code.

Afterwards the user is considered as valid and has the permission to log in.

The activation code of the user will not be cleared when an incorrect activation code is provided.

This resource can be used without authentication.

Please note that self-registered users which were not activated within 30 days are automatically deleted. Activation cannot be performed after these 30 days have passed.

Method

POST

Example URI

/selfregisteredusers/<userId>/activate/<activationcode>

Body Type

none

Return Type im:qualifiedUserName (see im.xsd)
Return Media-Type application/vnd.bosch-com.im+xml
Required Permissions none

Failure Description

400 Bad Request
The provided activation code has expired or isn't correct.

404 Not Found 
No matching user exists within IM.

Group Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest


Group - list

General description

Returns all groups matching the given filter.

Method

GET

Example URI

/groups?query=<PredicateFilter>
(see separate table for REST Predicate Filter description and examples)

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:group (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP

Failure description

400 Bad Request
The predicate filter is invalid.

401 Unauthorized
The current authenticated user is not permitted to read groups.

Group - create

General description

Creates a group as described in the XML body.

Method

POST

Example URI

/groups

Body type

im:group (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return type

im:group (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_GROUP

Failure description

401 Unauthorized 
The current authenticated user is not permitted to create a group.

400 Bad Request 
Mandatory information is missing in the XML body.

409 Conflict
A group with the same name already exists.

Group - read

General description

Returns more details about a specific group.

Method

GET

Example URI

/groups/<groupId>

Body type

none

Return type

im:group (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the group.

404 Not Found
No matching group exists within IM.

Group - update

General description

Updates the group as described in the XML body.

Method

PUT

Example URI

/groups/<groupId>

Body type

im:group (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return type

im:group (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_GROUP

Failure description

401 Unauthorized
The current authenticated user is not permitted to update the group.

For non-privileged users the operation will also fail with this status code if the user tried to assign a group to a parent group which (indirectly) contains permissions which are not contained in his identity context.

404 Not Found
No matching group exists within IM.

Group - delete

General description

Deletes the group.

Method

DELETE

Example URI

/groups/<groupId>

Parameter (Optional)

?permanently=true to erase the group instead of deleting it (in this case it cannot be restored)

Body type

none

Return type

none

Required Permissions DELETE_GROUP or
ERASE_GROUP to delete permanently

Failure description

401 Unauthorized
The current authenticated user is not permitted to delete the group.

404 Not Found
No matching group exists within IM.

Group - restore

General Description

Restores a deleted group.

Method

POST

Example URI

/groups/<groupId>

Body Type

none

Return Type

im:group (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_GROUP

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the group.

404 Not Found
No matching group exists within IM or the group is not deleted.

409 Conflict
The group could not be restored because the tenant it belongs to is deleted.
The group could not be restored because the parent group is deleted.

Group - i18n attributes

General Description

Returns all i18n attributes of the specified group.

Method 

GET

Example URI

/groups/<groupId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read groups.

404 Not Found 
No matching group exists within IM.

Group - list assigned users

General description

Returns a list of all users which are assigned to the specified group.

Method

GET

Example URI

/groups/<groupId>/users

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:user (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP and READ_USER

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the group.

404 Not Found
No matching group exists within IM.

Group - list assigned roles

General description

Returns a list of all roles which are assigned to the specified group.

Method

GET

Example URI

/groups/<groupId>/roles

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_GROUP and READ_ROLE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the group.

404 Not Found
No matching group exists within IM.

Role Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Role - list

General Description

Returns all roles that match the given filter.

Method 

GET 

Example URI

/roles?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE

Failure Description

400 Bad Request 
The predicate filter is invalid.

401 Unauthorized 
The current authenticated user is not permitted to read roles.

Role - create

General Description

Creates a role as described in the XML body.

Method

POST

Example URI

/roles

Body Type

im:role (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:role (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_ROLE

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized 
The current authenticated user is not permitted to create a role.

409 Conflict
A role with the same name already exists.

Tip: Find an example for the XML body required at Create a role using the Service API 1.

Role - read

General Description

Returns more details about the role.

Method 

GET 

Example URI

/roles/<roleId>

Body Type

none

Return Type

im:role (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the role.

404 Not Found 
No matching role exists within IM.

Role - update

General Description

Updates the role as described in the XML body.

Method

PUT

Example URI

/roles/<roleId>

Body Type

im:role (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:role (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to modify the role.

404 Not Found 
No matching role exists within IM.

Role - delete

General Description

Deletes the role.

Method

DELETE

Example URI

/roles/<roleId>

Parameter (Optional)

?permanently=true to erase the role instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions DELETE_ROLE or
ERASE_ROLE to delete permanently

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete the role.

404 Not Found 
No matching role exists within IM.

Role - restore

General Description

Restores a deleted role.

Method

POST

Example URI

/roles/<roleId>

Body Type

none

Return Type

im:role (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_ROLE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the role.

404 Not Found
No matching role exists within IM or the role is not deleted.

409 Conflict
The role could not be restored because the tenant it belongs to is deleted.
The role could not be restored because it is owned by an application instance which is deleted.

Role - i18n attributes

General Description

Returns all i18n attributes of the specified role.

Method 

GET

Example URI

/roles/<roleId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read roles.

404 Not Found 
No matching role exists within IM.

Role - list assigned users

General description

Returns a list of all users which are assigned to the specified role.

Method

GET

Example URI

/roles/<roleId>/users

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:user (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE and READ_USER

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the role.

404 Not Found
No matching role exists within IM.

Role - list assigned groups

General description

Returns a list of all groups which are assigned to the specified role.

Method

GET

Example URI

/roles/<roleId>/groups

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:group (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE and READ_GROUP

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the role.

404 Not Found
No matching role exists within IM.

Role - list assigned permissions

General description

Returns a list of all permissions which are assigned to the specified role.

Method

GET

Example URI

/roles/<roleId>/permissions

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:permission (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE and READ_PERMISSION

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the role.

404 Not Found
No matching role exists within IM.

Role - list assigned offerings

General description

Returns a list of all offering which are assigned to the specified role.

Method

GET

Example URI

/roles/<roleId>/offeringtypes

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:offeringType (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_ROLE and READ_OFFERING_TYPE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the offerings.

404 Not Found
No matching offering exists within IM.

Permission Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Permission - list

General Description

Returns all permissions that match the given filter.

Method 

GET 

Example URI

/permissions?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:permission (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_PERMISSION

Failure Description

400 Bad Request 
The predicate filter is invalid

401 Unauthorized 
The current authenticated user is not permitted to read permissions

Permission - create

General Description

Creates a permission as described in the XML body.

Method

POST

Example URI

/permissions

Body Type

im:permission (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:permission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_PERMISSION 

Failure Description

400 Bad Request
Mandatory information is missing in the XML body.

401 Unauthorized 
The current authenticated user is not permitted to create a permission.

409 Conflict
A permission with the same name already exists.

Permission - read

General Description

Returns more details about the permission specified.

Method

GET

Example URI

/permissions/<permissionId>

Body Type

none

Return Type

im:permission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_PERMISSION

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the permission.

404 Not Found 
No matching permission exists within IM.

Permission - update

General Description

Updates the permission as described in the XML body.

Method 

PUT 

Example URI

/permissions/<permissionId>

Body Type

im:permission (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:permission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_PERMISSION

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to modify the permission.

404 Not Found 
No matching permission exists within IM.

Permission - delete

General Description

Deletes the permission.

Method

DELETE

Example URI

/permissions/<permissionId>

Parameter (Optional)

?permanently=true to erase the permission instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions

DELETE_PERMISSION or
ERASE_PERMISSION to delete permanently

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete the permission.

404 Not Found 
No matching permission exists within IM.

Permission - restore

General Description

Restores a deleted permission.

Method

POST

Example URI

/permissions/<permissionId>

Body Type

none

Return Type

im:permission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_PERMISSION

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the permission.

404 Not Found
No matching permission exists within IM or the permission is not deleted.

409 Conflict
The permission could not be restored because the tenant it belongs to is deleted.
The permission could not be restored because it is owned by an application instance which is deleted.

Permission - i18n attributes

General Description

Returns all i18n attributes of the specified permission.

Method

GET

Example URI

/permissions/<permissionId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_PERMISSION

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read permissions

404 Not Found 
No matching permission exists within IM.

Permission - list assigned roles

General description

Returns a list of all roles which are assigned to the specified permission.

Method

GET

Example URI

/permissions/<permissionId>/roles

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_PERMISSION and READ_ROLE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the permission.

404 Not Found
No matching permission exists within IM.

Permission - list assigned offerings

General description

Returns a list of all offering types which are assigned to the specified permission.

Method

GET

Example URI

/permissions/<permissionId>/offeringtypes

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:offeringType (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_PERMISSION and READ_OFFERING_TYPE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the permission.

404 Not Found
No matching permission exists within IM.

Domain Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Domain - list

General Description

Returns all domains matching the given filter.

Method 

GET

Example URI

/domains?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:domain (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_DOMAIN

Failure Description

400 Bad Request 
The predicate filter is invalid.

401 Unauthorized 
The current authenticated user is not permitted to read domains.

Domain - create

General Description

Creates a domain as described in the XML body.

Method

POST

Example URI

/domains

Body Type

im:domain (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:domain (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_DOMAIN

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to create a domain.

400 Bad Request 
Mandatory information is missing in the XML body.

409 Conflict
A domain with the same name already exists.

Tip: Find an example for the XML body required at Create a domain using the Service API 1.

Domain - read

General Description

Returns more details about the domain.

Method

GET

Example URI

/domains/<domainId>

Body Type

none

Return Type

im:domain (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_DOMAIN

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the domain.

404 Not Found 
No matching domain exists within IM.

Domain - update

General Description

Updates the domain as described in the XML body.

Method

PUT

Example URI

/domains/<domainId>

Body Type

im:domain (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:domain (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_DOMAIN

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to update the domain.

404 Not Found 
No matching domain exists within IM.

Domain - delete

General description

Deletes the domain.

Method

DELETE

Example URI

/domains/<domainId>

Parameter (Optional)

?permanently=true to erase the domain instead of deleting it (in this case it cannot be restored)

Body type

none

Return type

none

Required Permissions

DELETE_DOMAIN or

ERASE_DOMAIN to delete permanently

Failure description

401 Unauthorized 
The current authenticated user is not permitted to delete the domain.

404 Not Found 
No matching domain exists within IM.

Domain - restore

General Description

Restores a deleted domain.

Method

POST

Example URI

/domains/<domainId>

Body Type

none

Return Type

im:domain (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_DOMAIN

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the domain.

404 Not Found
No matching domain exists within IM or the domain is not deleted.

409 Conflict
The domain could not be restored because the tenant it belongs to is deleted.


Domain - i18n attributes

General Description

Returns all i18n attributes of the specified domain.

Method 

GET

Example URI

/domains/<domainId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_DOMAIN

Failure Description

401 Unauthorized  
The current authenticated user is not permitted to read domains.

404 Not Found 
No matching domain exists within IM. 

Application Instance Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Application instance - list

General Description

Returns all application instances matching the given filter.

Method 

GET

Example URI

/instances?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:instance (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE

Failure Description

400 Bad Request 
The predicate filter is invalid.

401 Unauthorized 
The user is not logged-in.

Application instance - create

General Description

Creates an application instance described by the XML body.

Method

POST

Example URI

/instances

Body Type

im:instance (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:instance (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_INSTANCE

Failure Description

400 Bad Request
Mandatory information is missing in the XML body.

401 Unauthorized
The current authenticated user is not permitted to create an application instance.

409 Conflict
An application instance with the same name already exists.

Tip: Find an example for the XML body required at Create an application instance using the Service API 1.

Application instance - read

General Description

Returns more details about the application instance.

Method

GET

Example URI

/instances/<instanceId>

Body Type

none

Return Type

im:instance (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the application instance.

404 Not Found 
No matching application instance exists within IM.

Application instance - update

General Description

Updates the application instance as described in the XML body.

Method

PUT

Example URI

/instances/<instanceId>

Body Type

im:instance (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:instance (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_INSTANCE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to update the application instance.

404 Not Found 
No matching application instance exists within IM.

Application instance - delete

General description

Deletes the application instance.

Method

DELETE

Example URI

/instances/<instanceId>

Parameter (Optional)

?permanently=true to erase the application instance instead of deleting it (in this case it cannot be restored)

Body type

none

Return type

none

Required Permissions

DELETE_INSTANCE or

ERASE_INSTANCE to delete permanently

Failure description

401 Unauthorized 
The current authenticated user is not permitted to delete the application instance.

404 Not Found 
No matching application instance exists within IM.

Application instance - restore

General Description

Restores the deleted application instance.

Method

POST

Example URI

/instances/<instanceId>

Body Type

none

Return Type

im:instance (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_INSTANCE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the application instance.

404 Not Found
No matching application instance exists within IM or the application instance is not deleted.

409 Conflict
The application instance could not be restored because the tenant it belongs to is deleted.
The application instance could not be restored because the owning domain is deleted.

Application instance - i18n attributes

General Description

Returns all i18n attributes of the specified application instance.

Method 

GET

Example URI

/instances/<instanceId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read application instances.

404 Not Found 
No matching application instance exists within IM.

Application Instance - list assigned permissions

General description

Returns a list of all permissions which are assigned to the specified application instance.

Method

GET

Example URI

/instances/<instanceId>/permissions

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:permission (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE and READ_PERMISSION

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the application instance.

404 Not Found
No matching application instance exists within IM.

Application Instance - list assigned roles

General description

Returns a list of all roles which are assigned to the specified application instance.

Method

GET

Example URI

/instances/<instanceId>/roles

Body type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE and READ_ROLE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the application instance.

404 Not Found
No matching application instance exists within IM.

Application instance - resolve IDs

General Description

Resolve the IDs of application instances by providing their qualified names.

The result list contains the IDs of the application instances in the order of the specified qualified names.

If a specified application instance does not exist
or the user in whose context this command is executed is not allowed to see the application instance
an empty entry is inserted at the corresponding position in the result list.

Method

POST

Example URI

/instances/ids

Body Type

im:qualifiedInstanceNameList (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:entityIdList (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_INSTANCE

Failure Description

400 Bad Request 
The operation failed because of database related problems.

401 Unauthorized 
The user is not logged-in.

Application Instance Registration Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

The Application Instance Registration Resource allows to register a complete application instance with just one REST request.

This includes:

  • The creation of the application instance itself
  • The creation of application instance roles, permissions and offering types (including localizations)
  • Assignments between all these entities
  • Migration of existing application instances to new versions

The execution of this request is protected by the permission "INSTALL_APPLICATION".

The predefined role Application Installer includes this permission together with some additional permissions which are required in order to see the application instance and the related tenant and domain. This role allows also to see the application instance in the Adminstrator UI. The role is not part of the IM Default Offering and would thus not be auto-assigned to new tenants.

Application instance registration - create or migrate

General Description

Registers or migrates an application instance described by the XML body.

Method 

POST or PUT

Example URI

/instanceregistration

Body Type

im:instanceRegistration (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:instance (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions INSTALL_APPLICATION

Failure Description

400 Bad Request
Mandatory information is missing in the XML body,
the version of a migration has an invalid format,
or auto assignment was enabled for one of the contained offering types (this is a service internal feature).

401 Unauthorized
The current authenticated user is not permitted to create an application instance registration.

404 Not Found
The instance to migrate has been marked as deleted. Or an entity referenced by a migration step does not exist.

Tip: Find examples for the XML bodies in our examples chapter:

I18N Attribute Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

I18N Attribute - create

General description

Creates an I18NAttribute as described in the XML body.

Method

POST

Example URI

/i18nattributes

Body type

im:I18NAttribute (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return type

none

Return Media-Type

none

Required Permissions none

Failure description

400 Bad Request 
Mandatory information is missing in the XML body.

Tip: Find an example for the XML body required at Create an i18NAttribute using the Service API 1.

I18N Attribute - update

General Description

Updates an I18NAttribute as described in the XML body.

Method

POST

Example URI

/i18nattributes

Body type

im:I18NAttribute (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return type

none

Return Media-Type

none

Required Permissions none

Failure Description

400 Bad Request
Mandatory information is missing in the XML body.

I18N Attribute - delete

General Description

Deletes an I18NAttribute as described in the XML body.

Method

DELETE

Example URI

/i18nattributes/<entityId>/<locale>/<textfield>

Body type

none

Return type

none

Required Permissions none

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

404 Not Found
No matching I18NAttribute exists within IM.

User - Group Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

User - Group - create assignment

General Description

Assigns an user to a group.

Method

POST

Example URI

/relations/usergroup

Body Type

im:userGroup (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:userGroup (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_USER_GROUP, READ_USER and READ_GROUP

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to assign users to groups or to read the user or the group.

For non-privileged users the operation will also fail with this status code if the user tried to assign a group which (indirectly) contains permissions which are not contained in his identity context to a user.

404 Not Found
No matching user or group exists within IM.

409 Conflict
The user is already assigned to the group.

Tip: Find an example for the XML body required at Create a user - group assignment using the Service API 1.

User - Group - delete assignment

General Description

Removes an assignment between the given user and group.

Method

DELETE

Example URI

/relations/usergroup/<userId>/<groupId>

Body Type

none

Return Type

none

Required Permissions RELATION_USER_GROUP, READ_USER and READ_GROUP

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete user-group assignments or to read the user or the group.

404 Not Found
No matching user-group assignment exists within IM.

User - Role Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

User - Role - create assignment

General Description

Assigns a role to a user.

Method

POST

Example URI

/relations/userrole

Body Type

im:userRole (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:userRole (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_USER_ROLE, READ_USER and READ_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to assign users to roles or to read the user or the role.

For non-privileged users the operation will also fail with this status code if the user tried to assign a role which contains permissions which are not contained in his identity context to a user.

404 Not Found
No matching user or role exists within IM.

409 Conflict
The user is already assigned to the role.

Tip: Find an example for the XML body required at Create a user - role assignment using the Service API 1.

User - Role - delete assignment

General Description

Removes an assignment between the given user and role.

Method

DELETE

Example URI

/relations/userrole/<userId>/<roleId>

Body Type

none

Return Type

none

Required Permissions RELATION_USER_ROLE, READ_USER and READ_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete user-role assignments or to read the user or the role.

404 Not Found
No matching user-role assignment exists within IM.

Group - Role Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Group - Role - create assignment

General Description

Assigns a role to a group.

Method

POST

Example URI

/relations/grouprole

Body Type

im:grouprole (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:grouprole (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_GROUP_ROLE, READ_GROUP and READ_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to assign roles to groups or to read the role or the group.

For non-privileged users the operation will also fail with this status code if the user tried to assign a role which contains permissions which are not contained in his identity context to a group.

404 Not Found
No matching group or role exists within IM.

409 Conflict
The role is already assigned to the group.

Tip: Find an example for the XML body required at Create a group - role assignment using the Service API 1.

Group - Role - delete assignment

General Description

Removes an assignment between the given group and role.

Method

DELETE

Example URI

/relations/grouprole/<groupId>/<roleId>

Body Type

none

Return Type

none

Required Permissions RELATION_GROUP_ROLE, READ_GROUP and READ_ROLE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete group-role assignments or to read the role or the group.

404 Not Found
No matching group-role assignment exists within IM.

Role - Permission Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Role - Permission - create assignment

General Description

Assigns a permission to a role.

Method

POST

Example URI

/relations/rolepermission

Body Type

im:rolePermission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:rolePermission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required permissions RELATION_ROLE_PERMISSION, READ_ROLE and READ_PERMISSION

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to assign permissions to roles or to read the role or the permission.

For non-privileged users the operation will also fail with this status code if the user tried to assign permissions which are not contained in his identity context to a role.

404 Not Found
No matching role or permission exists within IM.

409 Conflict
The permission is already assigned to the role.

Tip: Find an example for the XML body required at Create a role - permission assignment using the Service API 1.

Role - Permission - delete assignment

General Description

Removes an assignment between the given role and permission.

Method

DELETE

Example URI

/relations/rolepermission/<roleId>/<permissionId>

Body Type

none

Return Type

none

Required permissions RELATION_ROLE_PERMISSION, READ_ROLE and READ_PERMISSION

Failure Description

401 Unauthorized
The current authenticated user is not permitted to delete role-permission assignments or to read the role or the permission.

404 Not Found
No matching role-permission assignment exists within IM.

Resources for data sharing between tenants
Offering Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

OfferingType - list
General Description Returns all offering types that match the given filter.
Method GET
Example URI> /offeringtypes?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)
Body Type none
Return Type atom:feed (see atom.xsd)
Return Media-Type application/atom+xml
Entry Content Type im:offeringType (see im.xsd)
Entry Content Media-Type application/vnd.bosch-com.im+xml
Required Permissions READ_OFFERING_TYPE

Failure Description

400 Bad Request 
The predicate filter is invalid.

401 Unauthorized 
The current authenticated user is not permitted to read offering types.

OfferingType - create

General Description

Creates a offering type as described in the XML body.

Method

POST

Example URI

/offeringtypes

Body Type

im:offeringType (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:offeringType (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_OFFERING_TYPE

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized 
The current authenticated user is not permitted to create a offering type.

409 Conflict
An offering type with the same name already exists.

Tip: Find an example for the XML body required at Create an Offering Type using the Service API 1.

OfferingType - read

General Description

Returns more details about the offering type.

Method

GET

Example URI

/offeringtypes/<offeringTypeId>

Body Type

none

Return Type

im:offeringType (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_OFFERING_TYPE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the offering type.

404 Not Found 
No matching offering type exists within IM.

OfferingType - update

General Description

Updates the offering type as described in the XML body.

Method

PUT

Example URI

/offeringtypes/<offeringTypeId>

Body Type

im:offeringType (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:offeringType (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_OFFERING_TYPE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to modify the offering type.

404 Not Found 
No matching offering type exists within IM.

OfferingType - delete

General Description

Deletes the offering type.

Method

DELETE

Example URI

/offeringtypes/<offeringTypeId>

Parameter (Optional)

?permanently=true to erase the offering type instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions

DELETE_OFFERING_TYPE or

ERASE_OFFERING_TYPE to delete permanently

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete the offering type.

404 Not Found 
No matching offering type exists within IM.

OfferingType - restore

General Description

Restores a deleted offering type.

Method

POST

Example URI

/offeringtypes/<offeringTypeId>

Body Type

none

Return Type

im:offeringType (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the offering type.

404 Not Found
No matching offering type exists within IM or the offering type is not deleted.

409 Conflict
The offering type could not be restored because the tenant it belongs to is deleted.
The offering type could not be restored because it is owned by an application instance which is deleted.

OfferingType - i18n attributes

General Description

Returns all i18n attributes of the specified offering type.

Method

GET

Example URI

/offeringtypes/<offeringTypeId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read offering types.

404 Not Found 
No matching offering type exists within IM.

OfferingType - list assigned permissions

General description

Returns a list of all permissions which are assigned to the specified offering type.

Method

GET

Example URI

/offeringtypes/<offeringTypeId>/permissions

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:permission (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_OFFERING_TYPE and READ_PERMISSION

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the offering type.

404 Not Found
No matching offering type exists within IM.

OfferingType - list assigned roles

General description

Returns a list of all roles which are assigned to the specified offering type.

Method

GET

Example URI

/offeringtypes/<offeringTypeId>/roles

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:role (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_OFFERING_TYPE and READ_ROLE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the offering type.

404 Not Found
No matching offering type exists within IM.

Tenant Relation Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

TenantRelation - list

General Description

Returns all tenant relation entities that match the given filter.

Method

GET

Example URI

/tenantrelations?query=<predicateFilter> 
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:tenantRelation (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT_RELATION

Failure Description

400 Bad Request 
The predicate filter is invalid.

401 Unauthorized 
The current authenticated user is not permitted to read tenant relation entities.

TenantRelation - create

General Description

Creates a tenant relation entity as described in the XML body.

Method

POST

Example URI

/tenantrelations

Body Type

im:tenantRelation (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenantRelation (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CREATE_TENANT_RELATION

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized 
The current authenticated user is not permitted to create a tenant relation entity.

409 Conflict
A tenant relation with the same name already exists.

Tip: Find an example for the XML body required at Create a Tenant Relation using the Service API 1.

TenantRelation - read

General Description

Returns more details about the tenant relation entity.

Method

GET

Example URI

/tenantrelations/<tenantRelationId>

Body Type

none

Return Type

im:tenantRelation (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT_RELATION

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to read the tenant relation entity.

404 Not Found 
No matching tenant relation entity exists within IM.

TenantRelation - update

General Description

Updates the tenant relation entity as described in the XML body.

Method

PUT

Example URI

/tenantrelations/<tenantRelationId>

Body Type

im:tenantRelation (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenantRelation (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_TENANT_RELATION

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to modify the tenant relation entity.

404 Not Found 
No matching tenant relation entity exists within IM.

TenantRelation - delete

General Description

Deletes the tenant relation entity.

Method

DELETE

Example URI

/tenantrelations/<tenantRelationId>
Parameter (Optional)

?permanently=true to erase the tenant relation instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions

DELETE_TENANT_RELATION or

ERASE_TENANT_RELATION to delete permanently

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete the tenant relation entity.

404 Not Found 
No matching tenant relation entity exists within IM.

TenantRelation - restore

General Description

Restores a deleted tenant relation entity.

Method

POST

Example URI

/tenantrelations/<tenantRelationId>

Body Type

none

Return Type

im:tenantRelation (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions UPDATE_TENANT_RELATION

Failure Description

401 Unauthorized
The current authenticated user is not permitted to restore the tenant relation entity.

404 Not Found
No matching tenant relation entity exists within IM or the tenant relation entity is not deleted.

409 Conflict
The tenant relation could not be restored because the tenant it belongs to is deleted.

TenantRelation - i18n attributes

General Description

Returns all i18n attributes of the specified tenant relation.

Method 

GET

Example URI

/tenantrelations/<tenantRelationId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT_RELATION

Failure Description

401 Unauthorized
The current authenticated user is not permitted to read tenant relations

404 Not Found 
No matching tenant relation exists within IM.

TenantRelation - list assigned offerings

General description

Returns a list of all offerings which are assigned to the specified tenant relation entity.

Method

GET

Example URI

/tenantrelations/<tenantRelationId>/offeringtypes

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:offeringType (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT_RELATION and READ_OFFERING_TYPE

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the assigned offering type entities.

404 Not Found
No matching tenant relation entity exists within IM.

TenantRelation - list assigned tenants

General description

Returns a list of tenants which are assigned to the specified tenant relation entity.

Method

GET

Example URI

/tenantrelations/<tenantRelationId>/tenants

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Entry Content Type

im:tenantType (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions READ_TENANT_RELATION and READ_TENANT

Failure description

401 Unauthorized
The current authenticated user is not permitted to read the consuming tenant entities.

404 Not Found
No matching tenant relation entity exists within IM.

Offering - Role Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Offering - Role - create assignment

General Description

Assigns a role to an offering type.

Method

POST

Example URI

relations/roleofferingtype

Body Type

im:offeringTypeRole (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:offeringTypeRole (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_ROLE_OFFERING_TYPE, READ_ROLE and READ_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to assign roles to offering types or to read the role or the offering type.

404 Not Found
No matching role or offering exists within IM.

409 Conflict
The role is already assigned to the offering type.

Tip: Find an example for the XML body required at Create a Role - Offering assignment using the Service API 1.

Offering - Role - delete assignment

General Description

Removes an assignment between the given role and offering type.

Method

DELETE

Example URI

/relations/roleofferingtype/<roleId>/<offeringTypeId>

Body Type

none

Return Type

none

Required Permissions RELATION_ROLE_OFFERING_TYPE, READ_ROLE and READ_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to delete role-offering type assignments or to read the role or the offering type.

404 Not Found
No matching role-offering type assignment exists within IM.

Offering - Permission Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Offering - Permission - create assignment

General Description

Assigns a permission to an offering type.

Method

POST

Example URI

/relations/permissionofferingtype

Body Type

im:offeringTypePermission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:offeringTypePermission (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_PERMISSION_OFFERING_TYPE, READ_PERMISSION and READ_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to assign permissions to offering types or to read the permission or the offering type.

404 Not Found
No matching offering type or permission exists within IM.

409 Conflict
The permission is already assigned to the offering type.

Tip: Find an example for the XML body required at Create a Permission - Offering assignment using the Service API 1.

Offering - Permission - delete assignment

General Description

Removes an assignment between the given offering type and the permission.

Method

DELETE

Example URI

/relations/permissionofferingtype/<permissionId>/<offeringTypeId>

Body Type

none

Return Type

none

Required Permissions RELATION_PERMISSION_OFFERING_TYPE, READ_PERMISSION and READ_OFFERING_TYPE

Failure Description

401 Unauthorized
The current authenticated user is not permitted to delete permission-offering type assignments or to read the permission or the offering type.

404 Not Found
No matching permission-offering type assignment exists within IM.

Tenant Relation - Offering Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Tenant Relation - Offering Type - create assignment

General Description

Assigns a tenant relation to an offering type.

Method

POST

Example URI

/relations/tenantrelationofferingtype

Body Type

im:tenantRelationOfferingType (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenantRelationOfferingType (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions RELATION_TENANT_RELATION_OFFERING_TYPE, READ_TENANT_RELATION and READ_OFFERING_TYPE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to assign tenant relations to offering types or to read the tenant relation or the offering type.

404 Not Found
No matching tenant relation or offering type exists within IM.

409 Conflict
The tenant relation is already assigned to the offering type.

Tip: Find an example at Create a Tenant Relation - Offering assignment using the Service API 1.

Tenant Relation - Offering Type - delete assignment

General Description

Removes an assignment between the given tenant relation and the offering type.

Method

DELETE

Example URI

/relations/tenantrelationofferingtype/<tenantRelationId>/<offeringTypeId>

Body Type

none

Return Type

none

Required Permissions RELATION_TENANT_RELATION_OFFERING_TYPE, READ_TENANT_RELATION and READ_OFFERING_TYPE

Failure Description

401 Unauthorized 
The current authenticated user is not permitted to delete the tenant relation - offering type assignment or to read the tenant relation or the offering type.

404 Not Found
No matching tenant relation - offering type assignment exists within IM.

Tenant Relation - Tenant Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Tenant Relation - Tenant - create assignment

General Description

Assigns a tenant to a tenant relation.

Method

POST

Example URI

/relations/tenantrelationtenant

Body Type

im:tenantRelationTenant (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:tenantRelationTenant (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions

RELATION_TENANT_RELATION_TENANT and READ_TENANT_RELATION

Note: In contrast to other relation resources this resource does not require READ_TENANT in order to support that the relation can be established more easily (it is sufficient to know the ID of the consuming tenant).

Failure Description

401 Unauthorized
The current authenticated user is not permitted to assign tenants to tenant relations or to read the tenant relation.

404 Not Found
No matching tenant relation or tenant exists within IM.

409 Conflict
The tenant is already assigned to the tenant relation.

Tenant Relation - Tenant - delete assignment

General Description

Removes an assignment between the given tenant and the tenant relation.

Method

DELETE

Example URI

/relations/tenantrelationtenant/<tenantRelationId>/<tenantId>

Body Type

none

Return Type

none

Required Permissions

RELATION_TENANT_RELATION_TENANT and READ_TENANT_RELATION

Note: In contrast to other relation resources this resource does not require READ_TENANT in order to support that the relation can be removed more easily (it is sufficient to know the ID of the consuming tenant).

Failure Description

401 Unauthorized
The current authenticated user is not permitted to delete tenant relation - tenant assignments or to read the tenant relation.

404 Not Found
No matching tenant relation - tenant assignment exists within IM.

Resources related to authentication
API Key Resource

An API Key is a secret token which a user can generate for himself using the Service API 1. The user can give the API Key to applications that should act on behalf of him, thus eliminating the need to authenticate via user name and password. While creating the API Key the user defines a sub-set of his roles and permissions that should be bound to the API Key.

While using an API Key for authentication, it is not possible to perform API Key related operations (e.g. show or create other API Keys).

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

API Key - list

General Description

Returns all API Keys of the the current authenticated user matching the given filter.

Method

GET

Example URI

/apikeys?query=<PredicateFilter>
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:apiKey (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions API_KEY_ADMINISTRATION

Failure Description

400 Bad Request
The predicate filter is invalid.

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

API Key - create

General Description

Creates an API Key as described in the XML body for the current authenticated user.

Method

POST

Example URI

/apikeys

Body Type

im:apiKey (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:apiKey (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions API_KEY_ADMINISTRATION

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

Tip: Find an example for the XML body required at Create an API-Key using the Service API 1. See as well the example in how to Create an Identity Context using the Service API 1 with an API-Key Authentication.

API Key - read

General Description

Returns more details about a specific API Key of the current authenticated user.

Method

GET

Example URI

/apikeys/<apiKeyId>

Body Type

none

Return Type

im:apiKey (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions API_KEY_ADMINISTRATION

Failure description

404 Not Found
No matching API Key exists for the user.

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

API Key - delete

General Description

Deletes an API Key that belongs to the current authenticated user.

Method

DELETE

Example URI

/apikeys/<apiKeyId>

Parameter (Optional) ?permanently=true to erase the API Key instead of deleting it (in this case it cannot be restored)

Body Type

none

Return Type

none

Required Permissions API_KEY_ADMINISTRATION

Failure description

404 Not Found
No matching API key exists for the user.

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

API Key - restore

General Description

Restores a deleted API Key.

Method

POST

Example URI

/apikeys/<apiKeyId>

Body Type

none

Return Type

im:apiKey (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions API_KEY_ADMINISTRATION

Failure Description

404 Not Found
No matching API Key exists for the user or the API Key is not deleted.

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

API Key - i18n attributes

General Description

Returns all i18n attributes of the specified API Key.

Method

GET

Example URI

/apikeys/<apiKeyId>/i18nattributes

Parameter (Optional)

?textField=NAME or DESCRIPTION (default: all fields)

?showDeleted=true or false (default: false)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:I18NAttribute (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions API_KEY_ADMINISTRATION

Failure Description

401 Unauthorized
The current user used an API Key for authentication or is not permitted to administrate API Keys.

404 Not Found 
No matching API Key exists within IM.

Authentication Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

IdentityContext - create

General Description

Creates an identity context for the given credentials. The credentials are either Tenant name/User name/Password or Tenant Id/User name/Password.

If user credentials are used for authentication, leading and trailing white spaces will be removed from the password.

All entities contained in the identity context are not localized (use Localized Identity Context Entities Resource in order to retrieve localized entities).

Method

POST

Example URI

/authentication

Parameter (Optional)

?sessionTimeout=sessionTimeoutInMinutes

The parameter sessionTimeout can be used to request a session with a custom timeout (it is not allowed to exceed the timeout defined via property im_session_timeout_max).

If not specified the session will expire after the timeout defined via property im_session_timeout_default.

?omitResponse=true or false (default: false)

The parameter omitResponse can be used in case you are not interested in the details of the created identity context, but you just want to check if the authentication with the provided credentials was successful.

When the parameter omitResponse is set to true, no response will be returned.

?idOnlyResponse=true or false (default: false)

The parameter idOnlyResponse can be used in case you are not interested in the details of the created identity context, but you just want to check if the authentication with the provided credentials was successful and you want to forward the context ID to another component.

When the parameter idOnlyResponse is set to true, only the identity context ID will be returned.

?refreshSupport=true or false (default: false)

The parameter refreshSupport can be used in case you want to receive an refresh token. The refresh token could be given to the authentication resource as credentials to create a new context or to create a new refreshed context. The refresh token should only be managed and used by the application which calls the authentication resource and should not be submitted to third party applications.

The refreshSupport parameter can only be used in conjunction with User Credentials (user name, tenant and password) and Refresh Context Token Credentials.

When the parameter refreshSupport is set to true, the response contains the header x-im-refresh-context-token with the token as value.

Body Type

im:authentication (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:identityContext (see im.xsd

im:contextId (see im.xsd ) for a request with the idOnlyResponse parameter

none for a request with the omitResponse parameter

Return Media-Type

application/vnd.bosch-com.im+xml (default)

Required Permissions none

Failure Description

400 Bad Request
Mandatory information is missing in the XML body.

401 Unauthorized
It is not permitted to create an identity context with the provided credentials.
Possible reasons: the provided credentials are invalid, the user is locked, or the user is not activated.

409 Conflict
The specified session timeout is too long and therefore not supported by the IM server.

429 Too Many Requests
In case the IM server is configured to perform rate limiting on failed login attempts and the user reached this limit.

Tip: Find examples for the XML body required at Identity Context related examples.

IdentityContext - read

General Description

Returns the identity context with the given context ID.

All entities contained in the identity context are not localized (use Localized Identity Context Entities Resource in order to retrieve localized entities).

Method

GET

Example URI

/authentication/<contextId>

Parameter (Optional)

?omitResponse=true or false (default: false)

When the parameter omitResponse is set to true, no response will be returned. This is useful in case you are not interested in the details of the created identity context, e.g. if you just want to check if the authentication with the provided credentials was successful.

Body Type

none

Return Type

im:identityContext (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml (default)

Required Permissions none

Failure Description

401 Unauthorized
No context found for the given ID.

Tip: Find an example at Retrieve an Identity Context using the Service API 1.

IdentityContext - invalidate

General Description

Invalidates the identity context with the given context ID.

An invalid context ID can not be used for authentication again. If the context with the given ID was used to create other identity contexts (act on behalf) these contexts will lose validity as well.

The Permissions service consists of multiple instances.

The invalidation of the identity context happens on one service instance where it has immediate effect.

It may take up to 15 minutes (in the worst case) until the identity context is invalidated on the other instances of Bosch IoT Permissions.

Method

DELETE

Example URI

/authentication/<contextId>

Body Type

none

Return Type

none

Required Permissions none
Failure Description none
Password Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Password - change password

General Description

Updates the password for the given user.

This resource allows to change expired passwords.

Leading and trailing white spaces will be removed from the current and the new password.

This resource can be used without authentication.

Method

PUT

Example URI

/password

Body Type

im:changePassword (see im.xsd)

Body Media-Type application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions none

Failure Description

400 Bad Request
Mandatory information is missing in the XML body, or the password is not valid according to the settings defined at the IM server, or the user is managed in an external system and cannot be updated within IM.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

401 Unauthorized
It is not permitted to update the password for the given user credentials. This can be caused for example if the credentials are missing or wrong.

429 Too Many Requests
In case the IM server is configured to perform rate limiting on failed login attempts and the user reached this limit.

Tip: Find an example for the XML body required at Change the password of a user without being authenticated.


Password - validate password

General Description

Validates the specified password using the password validation settings of the specified tenant.

The validation includes all checks which would be triggered when a user would be created in the specified tenant excluding the checks for password reuse and daily changes (as these could only be executed for a concrete user). 

Leading and trailing white spaces of the password are removed automatically before performing the checks.

This resource can be used without authentication.

Since release 4.4 it is possible to configure / use tenant-specific password settings.

As a result you need to provide the ID of the tenant and a flag indicating whether you want to validate against the rules of privileged or non-privileged users in addition to the password to validate.

If you do not provide these parameters the validation will be performed assuming that the password to check should be used in context of a non-privileged user of a tenant without tenant-specific password settings (the global default password settings are used in this case).

Method

POST

Example URI

/password/validation

Body Type

im:validatePassword (see im.xsd)

Body Media-Type application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions none

Failure Description

400 Bad Request
with an InvalidPasswordException as content

Example of a validation failure with some failed checks:

<?xml version="1.0" ?>
<exception 
    xmlns="http://www.bosch.com/IAP/im1_7_0">
    <errorCode>com.bosch.im.service.invalid.password</errorCode>
    <exceptionClass>
       com.bosch.im.service.InvalidPasswordException
    </exceptionClass>
    <message>The password is not valid.</message>
    <messageParameter></messageParameter>
    <messageParameter>NOT_ENOUGH_SPECIAL_CHARS=1</messageParameter>
    <messageParameter>INVALID_MIN_LENGTH=6</messageParameter>
    <messageParameter>WHITESPACE_NOT_ALLOWED</messageParameter>
</exception>

The first message parameter of the exception would contain the name of the user if the password is validated for a specific user (see for example Password - change password). For a full description of the format see InvalidPasswordException.

Password - send password reset email

General Description

Sends an email with a password reset link.

The user receiving the email needs to follow the link. There he is offered a dialog to define a new password. The password reset link will be valid for 30 minutes by default. The validity duration can be specified per tenant using tenant settings (see Tenant Resource).

The content of the email must be specified using the related email template (PASSWORD_RESET).
The email can be send only in case the email template exists for the tenant of the user, the server's email configuration properties are set and an email address was persisted for the user.

The password reset is triggered via Password - reset password.

This resource can be used without authentication.

The "password reset" functionality can be enabled and disabled via tenant settings (see Tenant Resource).

Method

POST

Example URI

/password/resetemail

Body Type

im:sendPasswordResetEmail (see im.xsd)

Body Media-Type application/vnd.bosch-com.im+xml

Return Type

none

Required Permissions none

Failure Description

400 Bad Request
Mandatory information is missing in the XML body or the email could not be sent (e.g. because of missing email address or invalid email template).
Or password reset is not enabled in the self service tenant settings.

(If userName and tenantId properties were specified, the failure can also be caused by the user is managed in an external system and cannot be updated within IM.)

404 Not Found
(will be raised only if userName and tenantId properties were specified)
No matching user exists within IM.

429 Too Many Requests
In case the IM server is configured to perform rate limiting for password reset emails and the user triggers a new password reset email shortly after the last one.

Tip: Find an example at Send a password reset email using the Service API 1.

Password - reset password

General Description

Allows a user to reset his password by providing a new password and the password reset code which was triggered via Password - send password reset email.

Resetting the password successfully will also reset the locked status and the failed login counter of the user.

Leading and trailing white spaces will be removed from the password.

In order to prevent brute-force attacks the reset code of the user will be cleared when an incorrect reset code is provided.

This resource can be used without authentication.

Method

POST

Example URI

/password/reset/<userId>

Body Type

im:resetPassword (see im.xsd)

Body Media-Type application/vnd.bosch-com.im+xml
Return Type none
Required Permissions none

Failure Description

400 Bad Request
Mandatory information is missing in the XML body, the password is not valid according to the password settings, the provided reset code has expired or isn't correct.

If the password validation fails an InvalidPasswordException will be thrown. For a full description of the message format see InvalidPasswordException.

404 Not Found 
No matching user exists within IM.

Localized Identity Context Entities Resource

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Localized IdentityContext entities - read

General Description

Returns the localized entities which are contained in or referenced from the identity context of the currently authenticated user.

Method

GET

Example URI

/localizedidentitycontextentities

Parameter (Optional)

?locale=<locale> (default: en)

Body Type

none

Return Type

im:localizedIdentityContext (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions none

Failure Description

401 Unauthorized
The user is not authenticated.

Tip: Find an example at Retrieve the localized entities of an Identity Context using the Service API 1.

Client Access Token Resource

The Client Access Token is used to authenticate your application at the IM service. The token itself consists of a client ID and a client secret.

It is essential that the received Client Access Token is kept secret and that it is only used by the bounded application or related components.
Find the full concept description at Client Access Token.

Bosch IoT Permissions - root URL at the Bosch IoT Cloud for Service API 1

https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest

Client Access Token - list

General Description

Returns all Client Access Tokens matching the given filter.

Method

GET

Example URI

/clientaccesstokens?query=<PredicateFilter>
(see separate table for REST Predicate Filter description and examples)

Body Type

none

Return Type

atom:feed (see atom.xsd)

Return Media-Type

application/atom+xml

Entry Content Type

im:clientAccessToken (see im.xsd)

Entry Content Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CLIENT_ACCESS_TOKEN_ADMINISTRATION

Failure Description

400 Bad Request
The predicate filter is invalid.

401 Unauthorized
The current user is not permitted to administrate Client Access Tokens.

Client Access Token - create

General Description

Creates a Client Access Token as described in the XML body.

Method

POST

Example URI

/clientaccesstokens

Body Type

im:clientAccessToken (see im.xsd)

Body Media-Type

application/vnd.bosch-com.im+xml

Return Type

im:clientAccessToken (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CLIENT_ACCESS_TOKEN_ADMINISTRATION

Failure Description

400 Bad Request 
Mandatory information is missing in the XML body.

401 Unauthorized
The current user is not permitted to administrate Client Access Tokens.

409 Conflict
The token could not be created because a limit was reached.

Tip: Find an example for the XML body required at Create a Client Access Token using the Service API 1.

Client Access Token - read

General Description

Returns more details about a specific Client Access Token.

Method

GET

Example URI

/clientaccesstokens/<catId>

Body Type

none

Return Type

im:clientAccessToken (see im.xsd)

Return Media-Type

application/vnd.bosch-com.im+xml

Required Permissions CLIENT_ACCESS_TOKEN_ADMINISTRATION

Failure description

404 Not Found
No matching Client Access Token exists for the user.

401 Unauthorized
The current user is not permitted to administrate Client Access Tokens.

Client Access Token - erase

General Description

Deletes a Client Access Tokent permanently.

Method

DELETE

Example URI

/clientaccesstokens/<catId>

Body Type

none

Return Type

none

Required Permissions CLIENT_ACCESS_TOKEN_ADMINISTRATION

Failure description

404 Not Found
No matching Client Access Token exists for the user.

401 Unauthorized
The current user is not permitted to administrate Client Access Tokens.

REST URL Parameters

REST Predicate Filter

To filter entities over RESTful services you can use the predicates. As a developer you can query filtering parameters within an URL while calling a RESTful service.

The value of the predicate query parameter query is defined as the URL encoded representation of a predicate string. The predicate syntax is described by the following grammar in BNF.

<predicate> ::= <predicateName> ( <subpredicate>[ , <subpredicate> ...] )
<subpredicate> ::= <predicate> | <value>
<value> ::= <text> | <id> | <boolean> | <fieldName>  | <operator>
<boolean> ::= true | false

<predicateName>: One of the supported predicates (see below)
<fieldName>
: The name of the field to compare (see section predicate fields)
<operator>: The operator to use for comparison (used by the any predicate)
<id>
: The UUID of an entity (36 characters) enclosed in double quotes

<text>: A sequence of unicode characters enclosed in double quotes

Here are some examples how to apply the syntax:

Example

Description

../users?query=any(FIRSTNAME, "Max", EQUAL)

Query all users with first name "Max".

../users?query=relationToGroup(name("Administrator"), true)

Query all users related to the group named "Administrator" (including users of child groups).

Available Predicates

The following sections describe all available predicates with their parameters and an example usage. Some predicates require an argument for a field of the queried resource. All available fields are described in a separate section below.

Predicates available for all basic entities
id

The id predicate queries a resource by its ID. The result is almost the same as for a query with the ID in the path; except that the result is contained in an atom feed entry. The id predicate is available for all basic entities.

Example Description
../users?query=id("ac103660-6bc1-11e2-9bc8-d4bed9157efb") Query a single user by the given ID.
name

The name predicate queries a resource by its name. The name is the technical name of the entity (not the internationalized name). The underlying operation is a "compare" with case insensitive. So in the following example the name could also be "admin" and would lead to the same result. The name predicate is available for all basic entities.

Example Description
../users?query=name("Admin") Query all users by the given name.
../users?query=name("admin") Leads to the same result as the previous example, because the compare is executed case insensitive.

If the name contains one or more quotes (") these characters must be escaped using a backslash (\").

When the current IdentityContext has access to just one tenant, querying for users by name will return at most one result, because the user name must be unique per tenant. I.e., when the current IdentityContext has access to more than one tenant, the query may return multiple results.

Therefore it is important to consider the name's uniqueness constraints which are documented for each entity.

not

The not predicate negates the containing predicate. It is available for all basic entities.

Example Description
../users?query=not(name("admin"))

Query all users named other than "admin".

../users?query=not(withAttribute("location", "Berlin")) Query all users which have either no "location" attribute or their value for attribute "location" is not "Berlin".
isNull

The isNull predicate queries entities which have a null value for a given field. The isNull predicate is available for all basic entities.

Example Description
../users?query=isNull(EMAIL)

Query all users whose email address field is not given.

any

The any predicate compares a field of the given entity. The first argument of the any predicate represents the field. The second attribute defines the value for which the compare should be executed. The last argument defines the operation.

Available operations are:

Operation Description
EQUAL Must be exactly the same.
EQUAL_IGNORE_CASE Must be the same, regardless of upper or lower case.
LIKE Must be contained.
LIKE_IGNORE_CASE Must be contained, regardless of upper or lower case.
START_WITH Must start with a specific value.
START_WITH_IGNORE_CASE Must start with a specific value, regardless of upper or lower case.
END_WITH Must end with a specific value.
END_WITH_IGNORE_CASE Must end with a specific value, regardless of upper or lower case.

The any predicate is available for all basic entities.

Example Description
../users?query=any(FIRSTNAME, "Max", LIKE_IGNORE_CASE)

Query all users with first name "Max", "Maximilian", "Maxwell", etc.

../groups?query=any(GROUP_PARENT_ID,"ca3672f0-7065-11e2-8628-d4bed9157efb",EQUAL) Query all groups which are the immediate children of a given group ID.

If the value specified as second argument of the predicate contains one or more quotes (") these characters must be escaped using a backslash (\").

Searching for the localized fields in relationTo predicates is currently not supported.

in

The in predicate allows to filter a single field which is in a given value list. The compare is done with an EQUAL operation.

Example Description
../users?query=in(FIRSTNAME, "Max", "John")

Query all users with first name "Max" or "John".

If the value specified as second argument of the predicate contains one or more quotes (") these characters must be escaped using a backslash (\").

all

The all predicate queries all entities without a filter. The all predicate is available for all basic entities.

Example Description
../users?query=all()

Query all users.

and

The and predicate combines several predicates by a logical AND-condition. The sub predicates are separated with a comma. The and predicate is available for all basic entities.

Example Description
../users?query=and(any(FIRSTNAME, "Max", LIKE), any(LASTNAME, "Schmidt", LIKE))

Query all users whose first name contains "Max" and last name contains "Schmidt".

or

The or predicate combines several predicates by a logical OR-condition. The sub predicates are separated with a comma. The or predicate is available for all basic entities.

Example Description
../users?query=or(any(FIRSTNAME, "Max", LIKE), any(LASTNAME, "Schmidt", LIKE))

Query all users whose first name contains "Max" or last name contains "Schmidt".

relationToTenant

The relationToTenant predicate is a predicate for querying entities which are owned by the tenants specified via the predicate parameter.

Example Description
../users?query=relationToTenant(name("DEFAULT"))

Query all users which belong to the tenant with name "DEFAULT".

Entity specific predicates
withAttribute

The withAttribute predicate allows to restrict a query for users by specifying user data attributes (it cannot be used for normal attributes of the user like first name, last name and email address).
The withAttribute predicate can only be used when querying for users.

Example Description
../users?query=withAttribute("location", "Berlin")

Query all users which have an attribute "location" with the value "Berlin".

../users?query=not(withAttribute("location", "Berlin")) Query all users which have either no "location" attribute or their value for attribute "location" is not "Berlin".
isLocked

The isLocked predicate allows to restrict a query for users to locked users.
The isLocked predicate can only be used when querying for users.

Example Description
../users?query=isLocked()

Query all users which are locked.

../users?query=not(isLocked()) Query all users which are not locked.
isActive

The isActive predicate allows to restrict a query for users to active users. Users are not active only if they are self-registered and not activated yet.

The isActive predicate can only be used when querying for users.

Example Description
../users?query=isActive() Query all users which are active.
../users?query=not(isActive()) Query all users which are not active.
isExternal

The isExternal predicate allows to restrict a query for users to users managed by external identity providers.

IM supports users which used an account in an external identity provider (e.g. Google) to login.

The isExternal predicate can only be used when querying for users.

Example Description
../users?query=not(isExternal()) Query all users which are not managed by an external identity provider.
../users?query=isExternal() Query all users which are managed by an external identity provider (e.g. Google).
../users?query=not(isNull(EXT_IDENTITY_PROV_TYPE)) Query all users which used an account in an external identity provider (e.g. Google) to login.
isSelfDeleted

The isSelfDeleted predicate allows to restrict a query for users to those who triggered themselves the deletion of their user account.

The  isSelfDeleted   predicate can only be used when querying for  users .

Example Description
../users?showDeleted=true&query=isSelfDeleted() Query all users who triggered themselves the deletion of their user account.
../users?showDeleted=true&query=not(isSelfDeleted ()) Query all deleted users excluding those who are marked as "self deleted".
isPrivileged

The isPrivileged predicate allows to restrict a query for users with a privileged user account.

The isPrivileged  predicate can only be used when querying for  users .

Example Description
../users?query=isPrivileged() Query all users who have a privileged user account.
../users?query=not(isPrivileged()) Query all non-privileged users.
isAllUsersGroup

The isAllUsersGroup predicate allows to restrict a query for groups to only retrieve the 'All Users' group of a tenant. The 'All Users' group is provided by IM and contains all users of the tenant

The isAllUsersGroup predicate can only be used when querying for groups.

Example Description
../groups?query=isAllUsersGroup() Query for the 'All Users' group of a tenant.
../groups?query=not(isAllUsersGroup()) Query all 'normal' groups excluding the 'All Users' group.
relationToDomain

The relationToDomain predicate is a predicate for querying tenants or instances which are related to the domains specified via the predicate parameter.

Example Description
../instances?query=relationToDomain(id("cbeaa371-c11d-11e1-8ba8-d4bed92ae488"))

Query all instances which have a relation to a domain with the given ID.

../tenants?query=relationToDomain(or(id("cbeaa371-c11d-11e1-8ba8-d4bed92ae488"),id("dbeaa371-c11d-11e1-8ba8-d4bed92ae488")))

Query the tenants which are the owners of the domains with the given IDs.

../tenants?query=relationToDomain(name("IAP")) Query the tenants which are the owners of the domain named "IAP".
relationToGroup

The relationToGroup predicate is a predicate for querying tenants, users, roles, or groups which are related to the groups specified via the predicate parameter.

The second parameter determines whether the group hierarchy should be analyzed in order to find relations via groups (true) or only direct relations should be treated as relation (false).
If no value is specified as second parameter the value false is used.

Note: When specifying true for the hierarchy the result depends on the type of the queried entity:

  • roles: includes in addition all roles which are related to PARENT groups of the specified group(s)
  • users: includes in addition all users which belong to CHILD groups of the specified group(s)
  • groups: includes in addition all CHILD groups of the specified group(s)
  • tenants: includes the owning tenants of the specified group(s), the flag is ignored
Example Description
../groups?query=relationToGroup(id("cbeaa371-c11d-11e1-8ba8-d4bed92ae488"),true)

Query all descendant groups for the specified group.

../roles?query=relationToGroup(id("cbeaa371-c11d-11e1-8ba8-d4bed92ae488"),false)

Query all roles which have a relation to the specified group.

../users?query=relationToGroup(or(id("cbeaa371-c11d-11e1-8ba8-d4bed92ae488"),id("1d45e070-7066-11e2-8628-d4bed9157efb")),false) Query all users which are assigned to one of the given groups.
relationToPermission

The relationToPermission predicate is a predicate for querying tenants, offering typesinstances, or roles which are related to the permissions specified via the predicate parameter.

Example Description
../roles?query=relationToPermission(any(NAME,"CREATE",LIKE_IGNORE_CASE))

Query roles which have any kind of a "CREATE" permission.

../instances?query=relationToPermission(or(id("abe09ae0-6bc1-11e2-9bc8-d4bed9157efb"),any(NAME,"CREATE",LIKE_IGNORE_CASE)))) Query all instances which have the given ID or any kind of "CREATE" permission.
relationToRole

The relationToRole predicate is a predicate for querying tenants, users, groups, permissions, instances, or offering types which are related to the roles specified via the predicate parameter.

The second parameter determines whether the group hierarchy should be analyzed in order to find relations via groups (true) or only direct relations should be treated as relation (false).
If no value is specified as second parameter the value false is used.

Note: When specifying true for the hierarchy the result depends on the type of the queried entity:

  • users: includes in addition all users which belong to a group with the specified role(s) (including users of CHILD groups)
  • groups: includes in addition CHILD groups of the groups with the specified role(s)
  • others: only direct relations are checked, the flag is ignored
Example Description
../users?query=relationToRole(name("Administrator"),true) Query users which have a relation to the "Administrator" role. This relation can be a direct assignment or an assignment via a group (hierarchical)
../groups?query=relationToRole(name("Administrator"),false) Query groups which have a direct assignment to the "Administrator" role.
../groups?query=relationToRole(name("Administrator")) Leads to the same result as the query before because false is the default value.
../permissions?query=relationToRole(name("Administrator")) Query permissions which are assigned to the "Administrator" role. 
../instances?query=relationToRole(name("Administrator")) Query instances which provide a role "Administrator".
relationToUser

The relationToUser predicate is a predicate for querying tenants, roles, or groups which are related to the users specified via the predicate parameter.

The second parameter determines whether the group hierarchy should be analyzed in order to find relations via groups (true) or only direct relations should be treated as relation (false).
If no value is specified as second parameter the value false is used.

Note: When specifying true for the hierarchy the result depends on the type of the queried entity:

  • roles: includes in addition all roles which are available for the specified user(s) because of groups (including roles which are assigned to PARENT groups)
  • groups: includes in addition all PARENT groups of the groups to which the specified user(s) belong(s)
  • tenants: includes the owning tenants of the specified user(s), the flag is ignored
Example Description
../roles?query=relationToUser(name("Admin"),false)

Query roles which are assigned directly to a user with the name "Admin".

../groups?query=relationToUser(name("Admin"),true) Query all groups which are assigned directly or by group hierarchy to a user with the name "Admin".
relationToInstance

The relationToInstance predicate is a predicate for querying tenants, domains, permissions, offering types, or instance roles which are related to the instances specified via the predicate parameter.

Example Description
../permissions?query=relationToInstance(id("cbeaa372-c11d-11e1-8ba8-d4bed92ae488"))

Query permissions which are related to a specific instance.

../domains?query=relationToInstance(id("cbeaa372-c11d-11e1-8ba8-d4bed92ae488")) Query the domain which owns the instance.
../roles?query=relationToInstance(id("cbeaa372-c11d-11e1-8ba8-d4bed92ae488")) Query roles which are exposed by the given instance.
Tenant Relation specific predicates
providerOf

The providerOf predicate is a predicate for querying tenants which are the providers of valid tenant relations.

Example Description
../tenants?query=providerOf(id("cbeaa373-c11d-11e1-8ba8-d4bed92ae488")) Query tenants which are providers of a specific tenant relation.
../tenants?query=providerOf(relationToOfferingType(relationToPermission(name(CREATE_USER)))) Query tenants which offer a specific permission.
withProvider

The withProvider predicate is a predicate for querying tenant relations where the given tenants are registered as provider of a tenant relation. The predicate returns only valid tenant relations.

Example Description
../tenantrelations?query=withProvider(id("cbeaa370-c11d-11e1-8ba8-d4bed92ae488")) Query tenant relations created by a specific provider tenant.
consumerOf

The consumerOf predicate is a predicate for querying tenants which are consumers of valid tenant relations.

Example Description
../tenants?query=consumerOf(id("cbeaa373-c11d-11e1-8ba8-d4bed92ae488")) Query tenants which are consumers of a specific tenant relation.
withConsumer

The withConsumer predicate is a predicate for querying tenant relations where the given tenants are registered as consumer of a tenant relation. The predicate returns only valid tenant relations.

Example Description
../tenantrelations?query=withConsumer(id("cbeaa370-c11d-11e1-8ba8-d4bed92ae488")) Query tenant relations that can be consumed by the given tenant.
applicableFor

The applicableFor predicate is a predicate for querying tenants which are applicable for offering types. The applicable tenant is the one in whose data the roles and permissions of the offering type can be used.

Example Description
../tenants?query=applicableFor(id("cbeaa374-c11d-11e1-8ba8-d4bed92ae488")) Query tenants which are applicable for a specific offering type.
../tenants?query=applicableFor(relationToPermission(name(CREATE_USER))) Query tenants which are applicable for a specific permission.
relationPartners

The relationPartners predicate is a predicate for querying tenants which are relation partners of the currently logged-in user (including the tenant to which the user belongs).

Example Description
../tenants?query=relationPartners() Query tenants which are relation partners of the currently logged-in user.
relationToOfferingType

The relationToOfferingType predicate is a predicate for querying tenants, tenant relations, instances, permissions, or roles which are related to the offering types specified via the predicate parameter.

Example Description
../permissions?query=relationToOfferingType(id("cbeaa374-c11d-11e1-8ba8-d4bed92ae488")) Query permissions which are related to a specific offering type
../roles?query=relationToOfferingType(id("cbeaa374-c11d-11e1-8ba8-d4bed92ae488")) Query roles which are related to a specific offering type
relationToTenantRelation

The relationToTenantRelation predicate is a predicate for querying tenants or offering types which are related to the tenant relation specified via the predicate parameter.

Example Description
../offeringtypes?query=relationToTenantRelation(id("cbeaa373-c11d-11e1-8ba8-d4bed92ae488")) Query offering types which are related to a specific tenant relation
Predicate Fields
Predicate fields available for all basic entities

Some predicates require a field definition as argument. This section provides an overview, which fields are available per entity.

All entities are providing the following fields. The additional fields are defined in the sections below.

Field Description Nullable

NAME

The name attribute of the entity. Cannot be localized.

FALSE

DESCRIPTION

The description attribute of the entity.  Can be localized. TRUE

LOCALIZED_NAME

The localized name (useful for querying an entity by a localized name, as the NAME itself cannot be localized). FALSE
Additional entity specific predicate fields
Tenant
Field Description Nullable
TENANT_ID

The technical ID of the tenant.

FALSE
CREATED_BY The ID of the tenant that has created this tenant. FALSE
User
Field Description Nullable
USER_ID

The technical ID of the user.

FALSE
FIRSTNAME The first name attribute of the user. TRUE
LASTNAME The last name attribute of the user. TRUE
EMAIL The email address attribute of the user TRUE
EXT_IDENTITY_PROV_TYPE

The type of the external OpenID connect provider which is used to authenticate this entity.
This property is only used for external users (e.g. Google). For all other users it is null.

TRUE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
Group
Field Description Nullable
GROUP_ID

The technical ID of the group.

FALSE
GROUP_PARENT_ID The technical ID of the parent group.
Might be null if the current group has no parent.
TRUE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
Role
Field Description Nullable
ROLE_ID

The technical ID of the role.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
INSTANCE_ID The application instance ID this entity belongs to.

Might be null if the role is not defined by an application instance but defined by a tenant.

TRUE
Permission
Field Description Nullable
PERMISSION_ID

The technical ID of the permission.

FALSE
INSTANCE_ID

The ID of the application instance this entity belongs to.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
Domain
Field Description Nullable
DOMAIN_ID

The technical id of the domain.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
Application Instance
Field Description Nullable
INSTANCE_ID

The technical ID of the instance.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
DOMAIN_ID The ID of the domain this entity belongs to. FALSE
OfferingType
Field Description Nullable
OFFERING_TYPE_ID

The technical ID of the offering type.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
INSTANCE_ID The ID of the application instance this entity belongs to. TRUE
APPLICABLE_SCOPE The scope of the offering type. Must be PROVIDER or CONSUMER. FALSE
Tenant Relation
Field Description Nullable
TENANT_RELATION_ID

The technical ID of the tenant relation.

FALSE
TENANT_ID The ID of the tenant this entity belongs to. FALSE
Predicate Filter overview
Filter User Group Role Perm. Domain App.
Inst.
Offering
Type
Tenant
Relation
Tenant
id ok ok ok ok ok ok ok ok ok
name ok ok ok ok ok ok ok ok ok
not ok ok ok ok ok ok ok ok ok
isNull ok ok ok ok ok ok ok ok ok
any ok ok ok ok ok ok ok ok ok
in ok ok ok ok ok ok ok ok ok
all ok ok ok ok ok ok ok ok ok
and ok ok ok ok ok ok ok ok ok
or ok ok ok ok ok ok ok ok ok
relationToTenant ok ok ok ok ok ok ok ok ok
withAttribute ok







isLocked ok







isActive ok







isExternal ok







isSelfDeleted ok







isPrivileged ok







isAllUsersGroup
ok






relationToDomain




ok

ok
relationToGroup ok ok ok




ok
relationToPermission

ok

ok ok
ok
relationToRole ok ok
ok
ok ok
ok
relationToUser
ok ok




ok
relationToInstance

ok ok ok
ok
ok
providerOf







ok
withProvider






ok
consumerOf







ok
withConsumer






ok
applicableFor







ok
relationPartners







ok
relationToOfferingType

ok ok
ok
ok ok
relationToTenantRelation





ok
ok
REST Result Sorting and Paging
Sorting

The query parameter sort allows to define the sort order for the result of a query.

A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending).

The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

The syntax of the sort parameter value is defined as follows:

sort                   = sort_criteria {"," sort_criteria}
sort_criteria          = field_name ":" ("ASC"|"DESC")
field_name             = alpha
alpha                  = (digit|character){digit|character};
digit                  = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9";
character              = lowercase_character|uppercase_character|special_character
special_character      = "_"
lowercase_character    = "a"|"b"|"c"|"d"|"e"|"f"|"g"|"h"|"i"|"j"|"k"|"l"|"m"|"n"
                         |"o"|"p"|"q"|"r"|"s"|"t"|"u"|"v"|"w"|"x"|"y"|"z";
uppercase_character    = "A"|"B"|"C"|"D"|"E"|"F"|"G"|"H"|"I"|"J"|"K"|"L"|"M"|"N"
                         |"O"|"P"|"Q"|"R"|"S"|"T"|"U"|"V"|"W"|"X"|"Y"|"Z";


An example URL with sort query parameter might look like the following:

/1/rest/users?sort=field_1:ASC,field_2:DESC,field_3:ASC
Paging

For querying large result sets over the internet, appropriate pagination is important. This is why we automatically apply pagination to all GET requests to collection resources.

You can configure pagination with the following parameters:

  • offset: the paging offset (default is 0).
  • limit: the maximum number of entries in a page (default is 25).

The maximum allowed value for limit is 200. When querying for groups the maximum allowed value is 1000 (this value might be decreased in a future version).

If you specify no or an invalid value for offset or limit, the default value will be used. If you specify a limit greater than the maximum, the maximum value will be used.

When you use the value 0 as limit, the result will contain no entities. This can be useful if you are only interested in getting the total amount of entries for the given query.


Example URLs:

URL
/ users?sort=name:ASC Sorts the users by name and returns the first 25 users (because default offset is 0 and default limit is 25)
/users?sort=name:ASC&limit=10 Sorts the users by name and returns the first 10.
/ users?sort=name:ASC&offset=10

Sorts the users by name and returns the next 25 (default limit) users after the 10th user, i.e. starting with the 11th user.

/ users?sort=name:ASC&offset=20&limit=10 Sorts the users by name and returns the next 10 users after the 20th user, i.e. starting with the 21th user.
/ users?sort=name:ASC&offset=100&limit=400 Sorts the users by name and returns the next 200 users (not 400, because 200 is the maximum limit) after the 100th user, i.e. starting with the 101th user.
/users?limit=0 Returns a result with no users but which contains the total amount of users.
REST API support for localized entity attributes

Entities within IM may have localized attributes, which means that these attributes have language-specific translations.

The localized attributes of entities are:

  • localizedName: the language-specific name. Can be used instead of the non-localized name attribute in i18N applications.
  • localizedDescription: the language-specific description. A non-localized description attribute is not provided.

The parameter locale allows to specify the preferred translation of the localized attributes when retrieving entities.

If there is no translation for the specified locale the following fall-back mechanism is applied:

  • If there is a translation for the specified locale, this translation is returned.
  • Fallback 1: If there is a translation for the default locale (Locale.ENGLISH), this translation is returned.
  • Fallback 2:
    • For the attribute localizedName the value of the corresponding non-localized attribute name is returned.
    • For the attribute localizedDescription an empty string is returned.

Example:

We assume that there exists a role with name DeviceAdmin and ID 83bd49c0-33d4-11e2-bcc2-d4bed9631538 which has two translations for the localizedName attribute:

  • English(en): Device Administrator
  • German(de): Geräte Administrator

So we will get the English translation of the attributes with the following GET request: /roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538?locale=en. Because English is the default language, we get the same result when

  • not specifying a locale at all: /roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538
  • specifying a locale for which there isn't a translation, such as French:  /roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538?locale=fr . (Note that in this special case, the response XML has another ns:locale, which is fr)
English translation of the DeviceAdmin role
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:role 
    xmlns="http://www.w3.org/2005/Atom" 
    xmlns:ns2="http://www.bosch.com/IAP/im1_1_0">
    <link rel="self" href=" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/update" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/delete" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/erase" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538?permanently=true"/>
    <link rel="http://www.bosch.com/iap/im/user/roles" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/83bd49c0-33d4-11e2-bcc2-d4bed9631538/roles"/>
    <link rel="http://www.bosch.com/iap/im/relations/userrole/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole"/>
    <ns2:id>83bd49c0-33d4-11e2-bcc2-d4bed9631538</ns2:id>
    <ns2:name>DeviceAdmin</ns2:name>
    <ns2:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns2:tenantId>
    <ns2:locale>en</ns2:locale>
    <ns2:localizedName>Device Administrator</ns2:localizedName>
    <ns2:localizedDescription></ns2:localizedDescription>
    <ns2:sid>83bd49c0-33d4-11e2-bcc2-d4bed9631538</ns2:sid>
    <ns2:instanceId>83aa0fe0-33d4-11e2-bcc2-d4bed9631538</ns2:instanceId>
</ns2:role>

For German, there is a translation, so we get Geräte-Administrator as value for the attribute localizedName for the GET request /roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538?locale=de:

German translation of the DeviceAdmin role
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:role 
    xmlns="http://www.w3.org/2005/Atom" 
    xmlns:ns2="http://www.bosch.com/IAP/im1_1_0">
    <link rel="self" href=" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/update" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/delete" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538"/>
    <link rel="http://www.bosch.com/iap/im/role/erase" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/roles/83bd49c0-33d4-11e2-bcc2-d4bed9631538?permanently=true"/>
    <link rel="http://www.bosch.com/iap/im/user/roles" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/83bd49c0-33d4-11e2-bcc2-d4bed9631538/roles"/>
    <link rel="http://www.bosch.com/iap/im/relations/userrole/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole"/>
    <ns2:id>83bd49c0-33d4-11e2-bcc2-d4bed9631538</ns2:id>
    <ns2:name>DeviceAdmin</ns2:name>
    <ns2:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns2:tenantId>
    <ns2:locale>de</ns2:locale>
    <ns2:localizedName>Geräte-Administrator</ns2:localizedName>
    <ns2:localizedDescription></ns2:localizedDescription>
    <ns2:sid>83bd49c0-33d4-11e2-bcc2-d4bed9631538</ns2:sid>
    <ns2:instanceId>83aa0fe0-33d4-11e2-bcc2-d4bed9631538</ns2:instanceId>
</ns2:role>
Parameters for deleting and restoring entities

The following sections describe how you can use the REST API to delete and restore entities.

Deletion of an entity

When you delete an entity, the entity will by default not be deleted permanently. This means that it is possible to restore it later on.

Example HTTP request:

//request
DELETE /users/35d00230-3487-11e2-84cd-d4bed9631538
 
//expected response
204 No Content
Permanent deletion of an entity

To erase an entity (delete it permanently), you have to use the parameter permanently.

Example HTTP request:

//request
DELETE /users/35d00230-3487-11e2-84cd-d4bed9631538?permanently=true
 
//expected response
204 No Content
Query deleted entities

Deleted entities are not returned by standard GET requests. However it is still possible to retrieve deleted entities by using the parameter showDeleted.

Query deleted entities on a collection resource

To get the first 10 deleted users, you could issue the following HTTP request:

GET /users?sort=name:ASC&offset=0&limit=10&showDeleted=true

If the showDeleted parameter is set to true, only deleted users will be contained in the result. It is not possible to get both deleted and non-deleted users with a single request.

Query a single deleted entity

To get a deleted user, you can issue a HTTP request like this:

GET /users/21505bc0-3487-11e2-84cd-d4bed9631538?showDeleted=true

If the showDeleted parameter is set to true when issuing a GET on a non-deleted entity, HTTP status 404 is returned.

Restore an entity

You can restore a deleted entity by issuing a POST request on the entity's resource.

Restore a non-tenant entity

To restore all IM entities except for tenant entities, all you need to specify is the ID of the deleted entity to be restored.

For example, a request to restore a user with ID   22e2e5d0-130f-11e4-889f-0800270070a2 , would look like this:

//request
POST /users/22e2e5d0-130f-11e4-889f-0800270070a2
 
//expected response body
<?xml version="1.0" ?>
<ns3:user 
    xmlns:ns3="http://www.bosch.com/IAP/im1_1_0" 
    xmlns:ns2="http://www.w3.org/2005/Atom">
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2" rel="self"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2" rel="http://www.bosch.com/iap/im/user/update"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2" rel="http://www.bosch.com/iap/im/user/delete"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2?permanently=true" rel="http://www.bosch.com/iap/im/user/erase"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2/i18nattributes" rel="http://www.bosch.com/iap/im/user/i18nattributes"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2/groups" rel="http://www.bosch.com/iap/im/user/groups"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/usergroup" rel="http://www.bosch.com/iap/im/relations/usergroup/create"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2/roles" rel="http://www.bosch.com/iap/im/user/roles"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole" rel="http://www.bosch.com/iap/im/relations/userrole/create"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/22e2e5d0-130f-11e4-889f-0800270070a2/userattributes" rel="http://www.bosch.com/iap/im/user/userattributes"></ns2:link>
    <ns3:id>22e2e5d0-130f-11e4-889f-0800270070a2</ns3:id>
    <ns3:name>test</ns3:name>
    <ns3:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns3:tenantId>
    <ns3:createdUserId>df4a0b90-130a-11e4-889f-0800270070a2</ns3:createdUserId>
    <ns3:updatedUserId>df4a0b90-130a-11e4-889f-0800270070a2</ns3:updatedUserId>
    <ns3:created>2014-07-24T10:47:25.872+02:00</ns3:created>
    <ns3:updated>2014-07-24T10:48:58.314+02:00</ns3:updated>
    <ns3:locale>en</ns3:locale>
    <ns3:localizedName>test</ns3:localizedName>
    <ns3:localizedDescription></ns3:localizedDescription>
    <ns3:markedAsDeleted>false</ns3:markedAsDeleted>
    <ns3:sid>22e2e5d0-130f-11e4-889f-0800270070a2</ns3:sid>
    <ns3:locked>false</ns3:locked>
    <ns3:emailAddress>test@test.de</ns3:emailAddress>
    <ns3:firstName>testFirstName</ns3:firstName>
    <ns3:lastName>testLastName</ns3:lastName>
    <ns3:active>true</ns3:active>
</ns3:user>
Restore a tenant entity

To restore a tenant entity, in addition to the tenant ID, you need to specify a user that would be automatically created and assigned as the admin user for the restored tenant.

For example, a request to restore a tenant with ID aefe8330-130f-11e4-889f-0800270070a2 , would contain the following information:

//request
POST /tenants/aefe8330-130f-11e4-889f-0800270070a2
 
//request body
<?xml version="1.0"?>
<im:user xmlns:im="http://www.bosch.com/IAP/im1_1_0">
   <im:name>RestoredTenantAdminUser</im:name>
   <im:firstName>John</im:firstName>
   <im:lastName>Arnold</im:lastName>
   <im:emailAddress>john.arnold@example.com</im:emailAddress>
   <im:password>Test1!</im:password>
</im:user>
 
//expected response body
<?xml version="1.0" ?>
<ns3:tenant 
    xmlns:ns3="http://www.bosch.com/IAP/im1_1_0" 
    xmlns:ns2="http://www.w3.org/2005/Atom">
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2" rel="self"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2" rel="http://www.bosch.com/iap/im/tenant/update"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2" rel="http://www.bosch.com/iap/im/tenant/delete"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2?permanently=true" rel="http://www.bosch.com/iap/im/tenant/erase"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2/i18nattributes" rel="http://www.bosch.com/iap/im/tenant/i18nattributes"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2/tenantrelations" rel="http://www.bosch.com/iap/im/tenant/tenantrelations"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/tenantrelationtenant" rel="http://www.bosch.com/iap/im/relations/tenantrelationtenant/create"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/tenants/aefe8330-130f-11e4-889f-0800270070a2/emailtemplates" rel="http://www.bosch.com/iap/im/tenant/emailtemplates/"></ns2:link>
    <ns3:id>aefe8330-130f-11e4-889f-0800270070a2</ns3:id>
    <ns3:name>TEST</ns3:name>
    <ns3:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns3:tenantId>
    <ns3:createdUserId>df4a0b90-130a-11e4-889f-0800270070a2</ns3:createdUserId>
    <ns3:updatedUserId>df4a0b90-130a-11e4-889f-0800270070a2</ns3:updatedUserId>
    <ns3:created>2014-07-24T10:51:20.932+02:00</ns3:created>
    <ns3:updated>2014-07-24T17:45:37.713+02:00</ns3:updated>
    <ns3:locale>en</ns3:locale>
    <ns3:localizedName>TEST</ns3:localizedName>
    <ns3:localizedDescription></ns3:localizedDescription>
    <ns3:markedAsDeleted>false</ns3:markedAsDeleted>
</ns3:tenant>

As the ID of the tenant to restore is specified as part of the URL, there is no need to specify the tenantId field for the admin user (it would be omitted).

Parameter for reducing the amount of transferred data

By default the Service API 1 is running in a verbose mode. This means that hypermedia links for entity creation, deletion, pagination and so on are added to the response messages.
When using the API 1 Client for Java, the Service API 1 will always be accessed in a non verbose mode.

  • verbose: if set to false, hypermedia links and feed titles are removed from response messages.

REST Response Format

When an operation is performed on a resource, the result is returned in form of XML which complies to the schema defined in im.xsd .

As the text contained in XML elements may contain illegal characters [<>&] the contentWhen an operation is performed on a resource, the result is returned in form of XML which complies to the schema defined in will then be wrapped in a CDATA definition like in the following example:

<im:localizedDescription>
    <![CDATA[Allows to assign greater values than 100 (value > 100)]]>
</im:localizedDescription>

As the value may also contain embedded code fragments like JavaScript code it is essential for applications which display values resolved from the REST API to sanitize them. This protects the application from cross-site scripting (XSS) attacks.


We distinguish following main categories of response types:

Single Value

Many operations - for example the create operation for a user - will return a XML representation of the object as result.
In this scenario the resulting XML will contain the values specified on user creation together with the unique ID of the user and a list of hypermedia links related to the newly created user.

<?xml version="1.0" ?>
<ns3:user 
    xmlns:ns3="http://www.bosch.com/IAP/im1_1_0" 
    xmlns:ns2="http://www.w3.org/2005/Atom">
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be" rel="self"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be" rel="http://www.bosch.com/iap/im/user/update"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be" rel="http://www.bosch.com/iap/im/user/delete"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be?permanently=true" rel="http://www.bosch.com/iap/im/user/erase"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be/groups" rel="http://www.bosch.com/iap/im/user/groups"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/usergroup" rel="http://www.bosch.com/iap/im/relations/usergroup/create"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be/roles" rel="http://www.bosch.com/iap/im/user/roles"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole" rel="http://www.bosch.com/iap/im/relations/userrole/create"></ns2:link>
    <ns2:link href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/083f3dd0-bc64-11e2-842b-d4bed91580be/userattributes" rel="http://www.bosch.com/iap/im/user/userattributes"></ns2:link>
    <ns3:id>083f3dd0-bc64-11e2-842b-d4bed91580be</ns3:id>
    <ns3:name>MyUser</ns3:name>
    <ns3:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns3:tenantId>
    <ns3:created>2013-05-14T09:00:59.576+02:00</ns3:created>
    <ns3:updated>2013-05-14T09:00:59.576+02:00</ns3:updated>
    <ns3:locale>en</ns3:locale>
    <ns3:localizedName>MyUser</ns3:localizedName>
    <ns3:localizedDescription></ns3:localizedDescription>
    <ns3:markedAsDeleted>false</ns3:markedAsDeleted>
    <ns3:sid>083f3dd0-bc64-11e2-842b-d4bed91580be</ns3:sid>
    <ns3:locked>false</ns3:locked>
    <ns3:emailAddress>myuser@test.de</ns3:emailAddress>
    <ns3:firstName>Max</ns3:firstName>
    <ns3:lastName>Mustermann</ns3:lastName>
</ns3:user>
Multiple Values

Query operations (e.g. a search for all users) will typically return multiple values. Therefore the result for these calls contains a list of entities in form of an atom:feed ( atom.xsd ).

Example of a list of users returned in form of an atom:feed:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <feed xmlns="http://www.w3.org/2005/Atom"
         xmlns:ns2="http://www.bosch.com/IAP/im1_1_0"
         xmlns:ns3="http://purl.org/syndication/history/1.0">
      <id>urn:uuid:e8dd2266-8a99-419f-ac20-5c7cfc82a89d</id>
      <title type="text">Users</title>
      <updated>2013-1-2T09:54:22.689+01:00</updated>
      <link rel="self" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users" />
      <link rel="http://www.bosch.com/iap/im/user/create" href=" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users" />
      <ns3:complete />
      <entry>
         <id>urn:uuid:40bee230-357a-11e2-a455-d4bed91580be</id>
         <title type="text">Admin</title>
         <content type="application/vnd.bosch-com.im+xml">
            <ns2:user>
               <link rel="self" href=" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/update" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/delete" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/erase"  href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be?permanently=true" />
               <link rel="http://www.bosch.com/iap/im/user/groups" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be/groups" />
               <link rel="http://www.bosch.com/iap/im/relations/usergroup/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/usergroup" />
               <link rel="http://www.bosch.com/iap/im/user/roles" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40bee230-357a-11e2-a455-d4bed91580be/roles" />
               <link rel="http://www.bosch.com/iap/im/relations/userrole/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole" />
               <ns2:id>40bee230-357a-11e2-a455-d4bed91580be</ns2:id>
               <ns2:name>Admin</ns2:name>
               <ns2:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns2:tenantId>
               <ns2:locale>en</ns2:locale>
               <ns2:localizedName>Admin</ns2:localizedName>
               <ns2:localizedDescription>Initial IM Administration User</ns2:localizedDescription>
               <ns2:sid>40bee230-357a-11e2-a455-d4bed91580be</ns2:sid>
               <ns2:locked>false</ns2:locked>
               <ns2:firstName>Admin</ns2:firstName>
               <ns2:lastName>Admin</ns2:lastName>
            </ns2:user>
         </content>
      </entry>
      <entry>
         <id>urn:uuid:40beeaaa-357a-11e2-a455-d4bed91580be</id>
         <title type="text">PowerUser</title>
         <content type="application/vnd.bosch-com.im+xml">
            <ns2:user>
               <link rel="self" href=" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/update" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/delete" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be" />
               <link rel="http://www.bosch.com/iap/im/user/erase"  href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be?permanently=true" />
               <link rel="http://www.bosch.com/iap/im/user/groups" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be/groups" />
               <link rel="http://www.bosch.com/iap/im/relations/usergroup/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/usergroup" />
               <link rel="http://www.bosch.com/iap/im/user/roles" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/users/40beeaaa-357a-11e2-a455-d4bed91580be/roles" />
               <link rel="http://www.bosch.com/iap/im/relations/userrole/create" href="https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest/relations/userrole" />
               <ns2:id>40beeaaa-357a-11e2-a455-d4bed91580be</ns2:id>
               <ns2:name>PowerUser</ns2:name>
               <ns2:tenantId>cbeaa370-c11d-11e1-8ba8-d4bed92ae488</ns2:tenantId>
               <ns2:locale>en</ns2:locale>
               <ns2:localizedName>Paul</ns2:localizedName>
               <ns2:localizedDescription>Power User Paul Smith</ns2:localizedDescription>
               <ns2:sid>40beeaaa-357a-11e2-a455-d4bed91580be</ns2:sid>
               <ns2:locked>false</ns2:locked>
               <ns2:firstName>Paul</ns2:firstName>
               <ns2:lastName>Smith</ns2:lastName>
            </ns2:user>
         </content>
      </entry>
   </feed>
No Content

For some operations it does not make sense to return a XML result. This is for example the case when deleting a user.

In this case the status code 204 is returned without XML content.

IM API Exception

When an operation cannot be performed because of a defined error situation (e.g. the currently logged-in user is not authorized to perform it) a status code >=400 and <500 is returned.

Detail information like the unique error code and the exception message are returned as XML content.

<?xml version="1.0" ?>
<exception 
    xmlns="http://www.bosch.com/IAP/im1_1_0">
    <errorCode>com.bosch.im.authorization.permissiondenied</errorCode>
    <exceptionClass>com.bosch.im.authorization.PermissionDeniedException</exceptionClass>
    <message>The permission [CREATE_USER] is not available for the current user.</message>
    <messageParameter>CREATE_USER</messageParameter>
</exception>
Missing or Invalid Authentication

When an operation cannot be performed because of missing or invalid authentication data status code 401 is returned.

In addition the standard HTTP header named WWW-Authenticate is provided.

An additional custom HTTP header named reason is used to inform the caller whether the authentication data is missing (missing-authentication-data) or if the provided credentials are invalid (invalid-credentials). 

Invalid Password

An InvalidPasswordException is raised when a specified password does not comply with the password rules defined at the IM server.

The exception contains the user and all failed checks in form of message parameters:

  • The first message parameter contains the name of the user for whom the password was validated.
    If a password is validated via the Password Resource, this message parameter will always be empty.
  • The following message parameters indicate which configured password rule failed.
    The message parameter will be in the format ERROR_CODE=CONFIGURED_VALUE for a rule which is configured with a number or just ERROR_CODE for a rule which can only be enabled or disabled.

The following error codes are defined:

Error Code Configuration Property
NOT_ENOUGH_UPPER_CASE_CHARS im_password_chars_upperCase
NOT_ENOUGH_SPECIAL_CHARS im_password_chars_special
NOT_ENOUGH_DIGITS im_password_chars_digits
TOO_MANY_REPEATED_CHARS im_password_chars_maxRepetition
INVALID_MIN_LENGTH im_password_length_min
INVALID_PASSWORD_REUSE im_password_history_length
TOO_MANY_DAILY_CHANGES im_password_change_maxPerDay
WHITESPACE_NOT_ALLOWED im_password_chars_allowWhitespace

Example exception:

<?xml version="1.0" ?>
<exception 
    xmlns="http://www.bosch.com/IAP/im1_7_0">
    <errorCode>com.bosch.im.service.invalid.password</errorCode>
    <exceptionClass>com.bosch.im.service.InvalidPasswordException</exceptionClass>
    <message>The password is not valid.</message>
    <messageParameter>John.Arnold</messageParameter>
    <messageParameter>NOT_ENOUGH_SPECIAL_CHARS=1</messageParameter>
    <messageParameter>INVALID_MIN_LENGTH=6</messageParameter>
    <messageParameter>WHITESPACE_NOT_ALLOWED</messageParameter>
</exception>
Other Exception

When an operation cannot be performed because of an undefined error situation (e.g. some technical problem with the server) status code 500 is returned.

The exception message is returned as XML content.

<?xml version="1.0" ?>
<exceptionMessage 
    xmlns="http://www.bosch.com/IAP/im1_1_0">
    Something went wrong...
</exceptionMessage>
Version Header

Each response of the IM server will contain the API version which is implemented by the server. This version information can be found in the HTTP header named v. An example value might be 1.7.

For accessing the version header you can simply execute a HTTP GET call to the root resource of IM. To reduce the traffic overhead you can attach the request parameter verbose with the value false.

Example request URL might be:
https://permissions-api.s-apps.de1.bosch-iot-cloud.com/1/rest
?verbose=false

Email template

Supporting user self-service related activities is an optional feature.

It consists of two parts: a UI and server side logic for user self-service related use-cases.

Most user self-service related use-cases require an interaction with the affected user via email.

Therefore these use-cases can only be used under the following preconditions:

  • An email address was persisted for the affected user.
  • The server's email configuration properties are set.
  • The corresponding email template exists for the tenant of the user.


Please consult the following pages in order to find out how to define your own customized email templates.

See as well further Examples related to user self-registration.

Email Template Syntax

The IM server allows to define email templates which are used to send emails for user self-service related use-cases.

The email templates can be customized per tenant and can be used only for users which belong to these tenants.

This section illustrates the syntax of an email template.

Template concept

An email template is defined with HTML and the FreeMarker template syntax (see http://freemarker.org/docs/ref_directives.html).

Here are some details about the basic template concept, relevant for writing a template:

  • The email template must be defined in HTML and must not contain any attachments or inline images.
  • The subject and optionally a reply to address must be defined inside the template using FreeMarker global variables.
  • The placeholders defined by IM can be used in the body part. These placeholders get replaced with IM data (e.g. user data), when the template is rendered into an email for a specific user.
  • Depending on the type of email, a link must be provided to trigger some activity in IM (e.g. to activate a user which was created by self-registration).
  • Internationalization: You can write a multi-language template, so that the user gets an email in his preferred language (see example below).
Example template – Activation email

An activation email is sent right after user self-registration, so that the user can activate his account. The email must contain an activation link which should be opened by the user. The link opens a site with a button which needs to be pressed by the user to trigger the activation.

The example below is valid in conjunction with self-service as your user self-registration service.

Activation email template
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<#global replyto="noreply@bosch-si.com"/>
<#assign url="https://permissions.s-apps.de1.bosch-iot-cloud.com/self-service/activateuser?code%3D${code}%26userId%3D${userId}%26imtid%3D${tenantId}"/>

<!--Activation email template in German-->
<#if language?starts_with("de")>
   <#global subject="Benutzerkonto aktivieren"/>
   </head>
   <body>
      <div style="padding: 20px; line-height: 30px;">
         Hallo ${userFirstName!} ${userLastName!},
         </br>
         um die Registrierung Ihres Benutzerkontos abzuschließen, klicken Sie bitte auf den folgenden Link:
         </br>
         <a href="${url}">
            Benutzerkonto aktivieren
         </a>
       </div>
   </body>
<!-- Activation email template in English and the default language-->
<#else>
   <#global subject="Activate account"/>
   </head>
   <body>
      <div style="padding: 20px; line-height: 30px;">
         Hello ${userFirstName!} ${userLastName!},
         </br>
         in order to complete the registration of your account, please click the following link:
         </br>
         <a href="${url}">
            Activate account
         </a>
       </div>
   </body>
</#if>
</html>

For instructions on constructing the link see Constructing links in templates.

Specifying email subject

The following variable can/must be defined:

Variable Description Required
replyto Email reply-to address no (if specified, it must be a valid email address)
subject Email subject yes

The variables need to be defined using the FreeMarker global variables syntax (see http://freemarker.org/docs/ref_directive_global.html).

Global variables example
<#global replyto="noreply@bosch-si.com"/>
<#global subject="Your Activation"/> 

The sender email address is a fix value for all Bosch IoT Permissions service installations.
The current value for BICS installations is: no-reply@bosch-iot.com

Placeholders

The following placeholders can be used within a template:

Placeholder Data type Description
${code} string

A user-specific technical code which was generated by IM, which allows to complete the use-case that corresponds to the email template (e.g. password reset).

This code must be included in the link which is generated for the user.

${language} string

The language chosen by the user (via the user profile).

For self-registered users the browser language is used as initial value.
For all other users English is used as initial value.

${localizedTenantName} string The tenant name in the user's language.
${tenantId} string The ID of the tenant which the user belongs to.
${tenantName} string The technical name of the tenant which the user belongs to. For the localized tenant name see the placeholder ${localizedTenantName}.
${userEmailAddress} string

The email address of the user.

Providing an email address is required for self-registered users.

${userFirstName} string

The first name of the user.

Providing the first name is optional.
You either need to ensure that the first name is defined for all affected users or use the FreeMarker syntax to handle missing values e.g. ${userFirstName!} or ${userFirstName?if_exists}
(See "Handling missing values" in FreeMarker Documentation at http://freemarker.org/docs/dgui_template_exp.html.)

${userId} string The ID of the user.
${userIsPrivileged} string The privileged state of the user ("true" or "false").
${userLastName} string

The last name of the user.

Providing the last name is optional.
You either need to ensure that the last name is defined for all affected users or use the FreeMarker syntax to handle missing values e.g. ${userLastName!} or ${userLastName?if_exists}
(See "Handling missing values" in FreeMarker Documentation at http://freemarker.org/docs/dgui_template_exp.html.)

${userName} string

The technical name of the user.

${userAttributes}

map

  • key - string
  • value - string

A key-value map, which stores the user specific attributes.

Providing the user attributes is optional.
You either need to ensure that the user attribute with the used key is defined for all affected users or use the FreeMarker syntax to handle missing values.
(See "Handling missing values" in FreeMarker Documentation at http://freemarker.org/docs/dgui_template_exp.html.)

If you want to use user attributes in your email template you need to know the keys of these user attributes.
If the user's telephone attribute exists as user attribute with key telephone the telephone number can be included in the email using ${userAttributes.telephone}.
(See "The Data-model" in FreeMarker Documentation at http://freemarker.org/docs/dgui_quickstart_datamodel.html.)

Constructing links in templates

The service server sends emails to users which make use of self-service features.

Depending on the type of the email, a link must be provided to trigger some activity  (e.g. to activate the user which was created by self-registration).

For the overall structure of an email template see section Email Template Syntax.

The default templates make use of links which point to a public self-service UI provided by the Bosch IoT Permissions service. If you are using a custom UI the links must be modified. This section shows how the default links are constructed.

User account activation link

This link is contained in an email which enables a self-registered user to activate his account so that he can log-in for the first time. This is an example for such a link:

https://permissions.s-apps.de1.bosch-iot-cloud.com/self-service/activateuser?
code=32346813&userId=74fb1487-1921-40fe-94ec-5b3fde42bfb6&imtid=476afb10-57c7-11e5-9df6-aa19aa04632c&ssoTargetUrl=%2Fprofile%3Fimtid%3D476afb10-57c7-11e5-9df6-aa19aa04632c

In the email template the account activation link is constructed like this:

Activation link template
${url}/activateuser?code=${code}&userId=${userId}&imtid=${tenantId}&ssoTargetUrl=${ssoTargetUrlContextPath}profile%3Fimtid%3D${tenantId}

You may want to change the following on this link template:

  • Own link for a custom User activation page
    If you have implemented a custom web page, you have to construct the link as supported by your own page. Please take a look at the email template and make use of the parameters provided by the service (e.g. Activation code, User data, Tenant ID, etc.)
  • No redirect after account activation
    The default behavior of the activateuser page is to redirect the user to the login page to display a success message after a successful account activation. This redirect behavior can be suppressed by adding &redirect=false to the link template
  • Custom target URL after activation and login
    After successful user activation and login, the parameter ssoTargerUrl is used to redirect the user to a target page. By default the User profile is shown. You may change the ssoTargerUrl parameter to an other target page. You must choose a target page provided by the service UI. A custom target page is only possible when providing an own UI implementation.
Password reset link

This link is contained in an email which enables a user to provide a new password when he forgot his current password. This is an example for such a link:

https://permissions.s-apps.de1.bosch-iot-cloud.com/self-service/passwordreset?
code=24718934&userId=74fb1487-1921-40fe-94ec-5b3fde42bfb6&imtid=476afb10-57c7-11e5-9df6-aa19aa04632c&uip=false&ssoTargetUrl=%2Fprofile%3Fimtid%3D476afb10-57c7-11e5-9df6-aa19aa04632c

In the email template the account activation link is constructed like this:

Password reset link template
${url}/passwordreset?code=${code}&userId=${userId}&imtid=${tenantId}&uip=${userIsPrivileged}&ssoTargetUrl=${ssoTargetUrlContextPath}profile%3Fimtid%3D${tenantId}

You may want to change the following on this link template:

  • Own link for a custom User activation page
    If you have implemented a custom web page, you have to construct the link as supported by your own page. Please take a look at the email template and make use of the parameters provided by the service (e.g. Reset code, Tenant ID, etc.)
  • Custom target URL after password reset and login
    After successful password reset and login, the parameter ssoTargerUrl is used to redirect the user to a target page. By default the User profile is shown. You may change the ssoTargerUrl parameter to an other target page. You must choose a target page provided by the service UI. A custom target page is only possible when providing an own UI implementation.
Email address confirmation link

This link is contained in an email which enables a user to change his email address.

In this use-case the email is used to verify that the email address is valid and that the user can access the inbox of the corresponding email account. This is an example for such a link:

https://permissions.s-apps.de1.bosch-iot-cloud.com/self-service/activateemail?
code=48862013&userId=74fb1487-1921-40fe-94ec-5b3fde42bfb6&imtid=476afb10-57c7-11e5-9df6-aa19aa04632c&ssoTargetUrl=%2Fprofile%3Fimtid%3D476afb10-57c7-11e5-9df6-aa19aa04632c

In the email template the email address confirmation link is constructed like this:

Email address confirmation link template
${url}/activateemail?code=${code}&userId=${userId}&imtid=${tenantId}&ssoTargetUrl=${ssoTargetUrlContextPath}profile%3Fimtid%3D${tenantId}

You may want to change the following on this link template:

  • Own link for a custom Emaill address confirmation page
    If you have implemented a custom web page, you have to construct the link as supported by your own page. Please take a look at the email template and make use of the parameters provided by the service (e.g. Reset code)
  • Custom target URL after email address confirmation and login
    After successful email address confirmation and login, the parameter ssoTargerUrl is used to redirect the user to a target page. By default the User profile is shown. You may change the ssoTargerUrl parameter to an other target page. You must choose a target page provided by the service UI. A custom target page is only possible when providing an own UI implementation.
Further tips to check a link

To test if the target page of a resulting link is actually available, proceed as follows:

  1. Take the link and replace the template placeholder ${code} with an arbitrary code (e.g. 123)
    and the template placeholder ${userId} with the ID of an existing user.
    1. User account activation example
      http://mydomain.com/im-ui-user-webapp/activateuser?code=123&userId=efa2b760-0803-11e4-af62-08002700300d&imtid=cbeaa370-c11d-11e1-8ba8-d4bed92ae488&ssoTargetUrl=/software-suite
    2. Password reset example
      http://mydomain.com/im-ui-user-webapp/passwordreset?code=123&userId=efa2b760-0803-11e4-af62-08002700300d&imtid=cbeaa370-c11d-11e1-8ba8-d4bed92ae48&ssoTargetUrl=/software-suite
    3. Email address confirmation example
      http://mydomain.com/im-ui-user-webapp/activateemail?code=123&userId=efa2b760-0803-11e4-af62-08002700300d&imtid=cbeaa370-c11d-11e1-8ba8-d4bed92ae48
  2. Open the URL with your browser.
  3. Click the button to proceed.
    Verify that a page with a failure message is displayed, stating for example that the code might be expired.
    If no such a page is displayed, your link does not follow the pattern described above.
  4. Log in with the user credentials of the user you used for the check. You should be redirected to the page specified with the ssoTargetUrl parameter.

IM JavaScript Support

The JavaScript REST API is exposed from the im-js-support-webapp component at URL: https://permissions-api.s-apps.de1.bosch-iot-cloud.com/js/1/rest/

This IM JavaScript Support API will be deprecated, as soon as we will provide JavaScript support for Service API 2.
JavaScript support for Service API 2 is already available with stability level BETA.

The API is kept for backward compatibility only, and for future implementations we highly recommend to use the API 2 which issues a JWT instead of an Identity Context.

For API 2 there is a support for browser based applications in BETA state. For details see JavaScript support for web applications.

The JavaScript support component contains a REST API which can be used by JavaScript clients for authentication purposes.
It is JSON-based and provides authentication resources as well as resources for validating and changing the password.

The JavaScript support component is complementary to the Service REST APIs, and covers just a subset of functionality for authentication.
Thus it allows custom JS applications to take part in the single-sign-on mechanism.
Main goal is to provide a reusable component for Web applications which need to access Bosch IoT Permissions service resources.

All resources and operations have the stability level Stable except the functionality is explicitly declared with another stability level.


REST Resources overview - JSON

The resources offered by JavaScript Support REST API are

  • /authentication
    • specifying the user credentials in the body.
    • using an API Key
    (for creating the SSO cookie containing the Identity Context ID)
  • /authentication/current
    (for reading, and deleting the SSO cookie)
  • /password
    (for setting a password in case it is expired)

REST Response Format - JSON

When an operation is performed on a resource, the result is returned in form of JSON. The JSON types are defined in the API documentation.

As the value may also contain embedded code fragments - like JavaScript code -  for applications which display values resolved from the JavaScript REST API it is essential to sanitize those fragments. This protects the application from cross-site scripting (XSS) attacks.

We distinguish following main categories of response types:

No Content

For some operations it does not make sense to return a result at all. This is for example the case when validating a password which complies with all password rules.

In this case the status code 204 is returned without JSON content.

IM API Exception

When an operation cannot be performed because of a defined error situation (e.g. the currently logged-in user is not authorized to perform it) a status code >=400 and <500 is returned.

Detail information like the unique error code and the exception message are returned as JSON content.

{
   "message" : "No identity context available",
   "errorCode" : "com.bosch.im.authorization.nocontext",
   "messageParameters" : []
}
Missing or Invalid Authentication

When an operation cannot be performed because of missing or invalid authentication data status code 401 is returned.

In addition the standard HTTP header named WWW-Authenticate is provided.

Invalid Password

An InvalidPasswordException is raised when a specified password does not comply with the password rules defined at the IM server.

The exception contains the user and all failed checks in form of message parameters:

  • The first message parameter contains the name of the user for whom the password was validated.
    If a password is validated via the Password Resource, this message parameter will always be empty.
  • The following message parameters indicate which configured password rule failed.
    The message parameter will be in the format ERROR_CODE=CONFIGURED_VALUE for a rule which is configured with a number or just ERROR_CODE for a rule which can only be enabled or disabled.

The following error codes are defined:

Error Code Configuration Property
NOT_ENOUGH_UPPER_CASE_CHARS im_password_chars_upperCase
NOT_ENOUGH_SPECIAL_CHARS im_password_chars_special
NOT_ENOUGH_DIGITS im_password_chars_digits
TOO_MANY_REPEATED_CHARS im_password_chars_maxRepetition
INVALID_MIN_LENGTH im_password_length_min
INVALID_PASSWORD_REUSE im_password_history_length
TOO_MANY_DAILY_CHANGES im_password_change_maxPerDay
WHITESPACE_NOT_ALLOWED im_password_chars_allowWhitespace

Example exception:

{
   message : "The password is not valid.",
   errorCode : "com.bosch.im.service.invalid.password",
   userName : "John.Arnold",
   failedRules : [ 
     {
        rule : "NOT_ENOUGH_SPECIAL_CHARS",
        value : 1
     }, {
        rule : "INVALID_MIN_LENGTH",
        value : 6
     }, {
        rule : "WHITESPACE_NOT_ALLOWED"
     } ]
}
Other Exception

When an operation cannot be performed because of an undefined error situation (e.g. some technical problem with the server) status code 500 is returned.

The exception message is returned as JSON content.

{
   "message" : "Something went wrong..."
}
Version Header

Each response of the IM JavaScript Support REST API will contain the API version which is implemented by the server. This version information can be found in the HTTP header named v. An example value might be 1.7.

Disabled Caching Headers

Each response of the IM JavaScript Support REST API will contain headers to disable browser side caching.

Service API 2

Service API 2 - Features

  • Services
    • Service API 2 is a JSON based RESTful HTTP API
    • Authentication service for users:
      • Authentication with tenant and user credentials
      • Authentication with Agent Credentials
      • Authentication with ID token based on JSON Web Token with custom expiration
      • Authentication and authorization for JavaScript Web applications
    • Authorization service for applications:
      • Authorization via Bosch ID (CIAM) or Bosch IoT Permissions ID token (Service API 2)
      • Authorization token based on JSON Web Token with customizable set of roles and permissions
      • Authorization check based in the permissions and roles of the authenticated user
    • Token validation
      • All issued tokens are signed and the signature can be validated by client
      • Public keys are provided in the JWK format
    • Application management
      • Register a new application with permissions, roles, and offerings
      • Migrate an existing application to a new version
      • Erase an application with all relations
    • Services to provide user self-service
      • Change forgotten password by providing a reset link sent via email or via project specific transport mechanism
      • Change password by providing the old one
      • Activate a self-registered user by providing an activation code sent via email or via project specific transport mechanism
      • Issue an activation code for password reset and account activation
      • Force a password reset for an user
  • Documentation