Quick Start¶
Getting started with using Security Identities and Privileges APIs involves the following steps:
- Create an account and a machine user.
- Create a JSON Web Token (JWT) by using the machine user credentials.
- Make API requests using the JWT.
Note
In the following examples we are:
Making use of a Linux/MacOS shell in which environmental variables are set using the
export
command. In other environments it may be different, e.g., Windows uses theset
command instead.Using the
curl
as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, JavaScript and Java.
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:
- Consume and create identities
- Consume privileges
List Identities¶
To fetch the user based by PARTITION
. size
parameter is an optional field and based on this value the response are returned (Note: size
should not exceed 1000). cursor
represent the last identity (identity from last page) id
from which the next set of identities can be fetched along with the size parameter. Incase all the identities returned on the current request, on the next request, the next
will be same as self
value with empty data
returned as response.
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
"https://securitymanager.siemens.com/sec-piam-v1/partitions/$PARTITION/identities?page[size]=2"
The response contains all details of individual identities.
{
"links":
{
"self": "/identities?page[size]=2",
"next": "/identities?page[size]=2&page[cursor]=7945"
},
"data":
[
{
"id": 7944,
"type": "Identity",
"attributes":
{
"firstName": "Christoper",
"lastName": "Adam",
"email": "christoper.adam@siemens.com",
"credentials": [
{
"cardNumber": "12345",
"id": "cf8112e0-3350-420b-b817-bc4bc9a58727",
"validity": {
"validForUnlimitedTime": true,
"validFromUtc": "2024-03-13T00:00:00Z",
"validToUtc": "0001-01-01T00:00:00Z"
},
"active": false
}
]
}
},
{
"id": 7945,
"type": "Identity",
"attributes":
{
"firstName": "Lucy",
"lastName": "Clare",
"email": "lucy.clare@siemens.com",
"credentials": [
{
"cardNumber": "123",
"id": "bf8112e0-3350-420b-b817-bc4bc9a58727",
"validity": {
"validForUnlimitedTime": true,
"validFromUtc": "2024-03-13T00:00:00Z",
"validToUtc": "0001-01-01T00:00:00Z"
},
"active": false
}
]
}
}
]
}
Add Identity¶
To add new identity. The request body should contain the type
and attributes
fields.
curl -X "POST" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
"https://securitymanager.siemens.com/sec-piam-v1/partitions/$PARTITION/identities"
with request body
{
"type": "Identity",
"attributes":
{
"firstName": "James",
"lastName": "Smith",
"email": "james.smith@siemens.com",
"credentials": [{
"cardNumber": "1211",
"validity": {
"validForUnlimitedTime": true,
"validFromUtc": "2024-03-13T00:00:00Z",
"validToUtc": "0001-01-01T00:00:00Z"
},
"active": false
}]
}
}
The response contains newly created identity.
{
"links":
{
"self": "/identities",
},
"data":
{
"id": 7946,
"type": "Identity",
"attributes":
{
"firstName": "James",
"lastName": "Smith",
"email": "james.smith@siemens.com",
"credentials": [{
"cardNumber": "1211",
"id": "dc8112e0-3350-420b-b817-bc4bc9a58727",
"validity": {
"validForUnlimitedTime": true,
"validFromUtc": "2024-03-13T00:00:00Z",
"validToUtc": "0001-01-01T00:00:00Z"
},
"active": false
}]
}
}
}
List Privileges¶
To fetch the privileges based by PARTITION
.
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
"https://securitymanager.siemens.com/sec-piam-v1/partitions/$PARTITION/privileges"
The response contains all details of individual privileges.
{
"links":
{
"self": "/privileges"
},
"data":
[
{
"id": 11423,
"type": "Privilege",
"attributes": {
"name": "Privilege sample",
"description": "Privilege description"
}
},
{
"id": 11424,
"type": "Privilege",
"attributes": {
"name": "Privilege sample",
"description": "Privilege description"
}
}
]
}
Note
For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the Developer's Guide.