Quick Start¶

Welcome to the Sustainability API Quick Start guide! This document will walk you through the essential steps to authenticate and interact with the Sustainability APIs, from account creation to making your first API requests.

Prerequisites¶

Before you begin, ensure you have:

• Access to the Fire API portal.
• Credentials for a machine user (clientId, clientSecret, and customerId).
• A terminal environment (Linux/MacOS shell or Windows command prompt).
• curl installed, or another HTTP client of your choice.

Step 1: Create an Account and Machine User¶

To access the Fire APIs, you need to create an account and register a machine user. Follow the instructions in the Getting Started guide to obtain your clientId, clientSecret.

You need to get your customerID as well.

Step 2: Obtain a JSON Web Token (JWT)¶

Authenticate your machine user by generating a JWT. This token will be used to authorize your API requests.

Example: Generate a Token¶

Set your credentials as environment variables:

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

Endpoint: POST {{buildingxopenness.env.issUrl}}

Body Parameters:

• client_id (string, required): Your machine user's client ID.
• client_secret (string, required): Your machine user's client secret.
• audience (string, required): The audience for the token, typically the API identifier.
• grant_type (string, required): The OAuth2 grant type, usually client_credentials.

Example:

curl {{buildingxopenness.env.issUrl}} \
    -H 'content-type: application/json' \
    -d "{
                \"client_id\":\"$CLIENT_ID\",
                \"client_secret\":\"$CLIENT_SECRET\",
                \"audience\":\"{{buildingxopenness.env.audience}}\",
                \"grant_type\":\"client_credentials\"
            }"

Note:

• The above example uses a Linux/MacOS shell. On Windows, use set instead of export.
• You can use any HTTP client or programming language to make these requests.

Example Response¶

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

• The access_token is your JWT.
• The expires_in value (in seconds) indicates how long the token is valid (typically 24 hours).

Step 3: Make API Requests¶

With your token and customer ID, you can now interact with the Sustainability API.

Retrieve Utility Data¶

You can fetch the utility data for a customer by performing the GET Utility Data operation.

Endpoint: GET customers/{$customerID}/assets/utility-data

Path Parameters:

• customerID (string, required): The unique identifier of the customer.

Query Parameters:

• customerName (string, required): Name of the customer.
• pageSize (number, optional): Specifies the response size.
• serviceType (string, optional): Specifies the service type.

Example:

You can fetch the utility data for a customer by performing the GET Utility Data operation.

curl -H "Authorization: Bearer $TOKEN" \
    "{{buildingxopenness.env.sustainabilityApiUrl}}/customers/$CUSTOMER/assets/utility-data"

• The response includes a list of buildings with utility data assets for customers.
• For large customers, refer to the Pagination section.