Quick Start¶

Getting started with using Activities APIs involves the following steps:

1. Create an account and a machine user.
2. Create a JSON Web Token (JWT) by using the machine user credentials.
3. Make API requests using the JWT.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://siemens-bt-015.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }" 

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token property in the response. You can now use it by passing it in the Authorization header of any subsequent API requests. The expires_in property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed, you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to:

1. Consume activities

List Customer Level Activities¶

To fetch activities at the customer (company) level, use the following v2 endpoint.

Note: Access to this endpoint requires the af.customer.read permission.

curl -H "Authorization: Bearer $TOKEN" \
    "https://eu.buildingx.siemens.com/api/openness/sec-activities/v2/customers/$CUSTOMER_ID?page[size]=2"    

The response structure will include a links.next property with a page[cursor] value for retrieving the next page of results:

{
  "links": {
    "self": "/activities?page[size]=2",
    "next": "/activities?page[size]=2&page[cursor]=6478632ea30ccb58b630b273"
  },
  "data": [
    {
      "type": "Activity",
      "id": "6478632ea30ccb58b630b272",
      "attributes": {
        "title": "User group created",
        "description": "A new user group was created at the company level.",
        "eventType": "Operator",
        "severity": "Low",
        "category": "User operation",
        "subCategory": null,
        "created": "2023-06-01T09:21:50.356Z",
        "recorded": "2023-06-01T09:21:52.868Z",
        "subSystem": "Security Manager",
        "origin": "User Management"
      }
    }
    // ... more activities ...

List Partition Level Activities¶

To fetch partition level activities using the v2 endpoint,, use the following v2 endpoint.

Note: Access to this endpoint requires the af.partition.read permission.

curl -H "Authorization: Bearer $TOKEN" \
    "https://eu.buildingx.siemens.com/api/openness/sec-activities/v2/customers/$CUSTOMER_ID/partitions/$PARTITION_ID/?page[size]=2"

The response structure will include a links.next property with a page[cursor] value for retrieving the next page of results:

{
  "links": {
    "self": "/activities?page[size]=2",
    "next": "/activities?page[size]=2&page[cursor]=6478632ea30ccb58b630b273"
  },
  "data": [
    {
      "type": "Activity",
      "id": "6478632ea30ccb58b630b272",
      "attributes": {
        "title": "Identity deleted",
        "description": "Identity Performance Test - Security API - First Name Performance Test - Security API - Last Name was deleted",
        "eventType": "Operator",
        "severity": "Low",
        "category": "User operation",
        "subCategory": null,
        "created": "2023-06-01T09:21:50.356Z",
        "recorded": "2023-06-01T09:21:52.868Z",
        "subSystem": "Siveillance Access",
        "origin": "Identity Management"
      }
    }
    // ... more activities ...
  ]
}