SOUP Authentication

Bosch.IdM

The System Software Update service uses Bosch.IdM for user authentication. After a successful login, an access token is generated. This token contains all Bosch.IdM roles of this particular user in the scopes. It is then used for requests against the System Software Update service and serves as the basis for request authorization.

IoT Rollouts Auth OAuth2 clients

An OAuth2 client follows the standard protocol and can be used to obtain a Rollouts Auth access token for authentication of your application when using System Software Update API endpoints.

The OAuth2 clients UI feature allows you to create, list, filter, view, and manage OAuth2 clients, and use them to create access tokens.

OAuth2 clients do not provide any user context information. They can only be limited by the scopes selected at the time of creation. Please find the supported scopes at SOUP Authorization.

NOTE

Learn how to set up a new OAuth2 client at Set up an OAuth2 client.

DSI API keys

As an alternative to Rollouts Auth access tokens, the device-facing DSI API (Direct System Integration) accepts tenant-bound API keys. An API key is a long-lived static credential for backends or gateways that cannot obtain OAuth2 access tokens.

Properties

• Limited validity: every key has a mandatory expiry date of at most 365 days after creation. Expired keys are rejected.
• Shown once: the key is only returned in the response of the create request. SOUP stores just a SHA-256 hash of the key, so a lost key cannot be recovered. Create a new key instead.
• Limited number: a tenant can hold 2 DSI API keys by default, which allows rotation (quota DSI_API_KEYS_MAX_COUNT). Expired keys count until they are deleted.
• Usage tracking: for each key, SOUP shows the last day (UTC) on which it was used successfully (lastUsedOn).

Managing API keys

API keys are managed with the SOUP Management API. This requires the API_KEY permissions, which are granted to the SYSTEM_ADMIN role and the management-full-access scope.

Method	Path	Description
POST	/api/mgmt/v1/api-keys/dsi	Create a key (name, optional description, expiresAt). Returns the key once.
GET	/api/mgmt/v1/api-keys/dsi	List the keys of the tenant (without the secret).
GET	/api/mgmt/v1/api-keys/dsi/{id}	Get a single key (without the secret).
PUT	/api/mgmt/v1/api-keys/dsi/{id}	Replace the description of a key (null removes it). name and expiresAt are immutable, create a new key to extend the validity.
DELETE	/api/mgmt/v1/api-keys/dsi/{id}	Revoke and delete a key.

A key has the format dsik_<id>_<secret>_<checksum>. The <id> is the id of the key returned by the Management API, so you can always tell which key a client uses.

Using an API key

Send the key in the Authorization header with the ApiKey scheme:

GET /{tenant}/controller/v1/{controllerId} HTTP/1.1
Host: dsi.eu1.bosch-iot-rollouts.com
Authorization: ApiKey dsik_AbCdEf123456_...

Invalid, unknown, revoked or expired keys, and keys used with another tenant, are answered with 401 Unauthorized and WWW-Authenticate: ApiKey.

!!! tip The ApiKey scheme prefix is optional: a header value consisting of just the key (Authorization: dsik_...) is accepted as well.

Rotating an API key

1. Create a second key with POST /api/mgmt/v1/api-keys/dsi.
2. Switch the client to the new key.
3. Check that lastUsedOn of the new key is updated and that the old key is no longer used.
4. Delete the old key with DELETE /api/mgmt/v1/api-keys/dsi/{id}.

!!! note After a delete, the key is revoked within seconds: SOUP propagates the change to the DSI service asynchronously.