Getting Started

Getting started with using Electrification X APIs involves the following steps:

1. Get credentials for authorization
2. Create a JSON Web Token (JWT) by using the credentials
3. Make API requests using the JWT

Get credentials¶

Your company administrator must follow the Setting up a machine user guide to generate your Client ID and Client Secret. Share that link with your administrator when requesting credentials.

Your company administrator will provide you with the following credentials:

• Client ID
• Client Secret

Create a token¶

For the Electrification X API you need a Client ID and a Client Secret to get an access token.

The authentication endpoint and audience differ by region:

The following parameters are used in the token request:

Example request (cURL)¶

curl -X POST "${AUTH_ENDPOINT}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "'"${CLIENT_ID}"'",
    "client_secret": "'"${CLIENT_SECRET}"'",
    "audience": "'"${AUDIENCE}"'",
    "grant_type": "client_credentials"
  }'

Example request (Python)¶

import requests  # Prerequisite: pip install requests

def authenticate(auth_endpoint: str, client_id: str, client_secret: str, audience: str) -> str:
    response = requests.post(
        auth_endpoint,
        headers={'Content-Type': 'application/json'},
        json={
            'client_id': client_id,
            'client_secret': client_secret,
            'audience': audience,
            'grant_type': 'client_credentials',
        },
    )
    response.raise_for_status()
    message = response.json()
    return message['access_token']

Example response¶

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

The access token is a JWT (JSON Web Token). It is the value of the access_token-property in the response. 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 by repeating the same POST request with your Client ID and Secret.

Important: Reuse your token for the entire duration of its validity. Do not generate a new token for every API request — excessive token generation will be billed to your account. Cache the token and only request a new one when the current token has expired or is near expiration.

Error responses¶

Make API requests¶

Include the following headers in all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

The API base URL depends on your region:

Rate limiting: All API endpoints are rate-limited. If you receive HTTP 429 (Too Many Requests), implement exponential backoff and retry logic in your client.

Example request (cURL)¶

curl -X GET "${API_BASE_URL}/v1/me" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

Example request (Python)¶

import requests  # Prerequisite: pip install requests

def get_me(api_base_url: str, access_token: str) -> dict:
    response = requests.get(
        f'{api_base_url}/v1/me',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
    )
    response.raise_for_status()
    return response.json()

Example response¶

{
  "data": {
    "id": "12345678-1234-1234-1234-123456789012",
    "type": "User",
    "attributes": {
      "externalId": "r4nd0mStr1ngExAmpl3@clients"
    },
    "relationships": {
      "customers": {
        "links": {
          "related": "https://api.electrificationx.siemens.com/v1/me/customers"
        }
      }
    }
  },
  "links": {
    "self": "https://api.electrificationx.siemens.com/v1/me"
  }
}

See the API Reference for all available endpoints and the API overview for a description of the available entities and their relationships.