Authentication (v2)

How to authenticate to the InnerSpace API

Summary

The InnerSpace API authenticates M2M clients using a session token. Exchange your credentials once at /v2/oauth/token to receive a session_id, then include it as a header on all subsequent API calls.

Developer Access

Contact [email protected] for developer access. They will provide you with a ClientID and ClientSecret.

They will need to know the usage of the credentials - whether it is needed for a backend service, a native application, a single-page web app or regular web app.

Backend Services

Backend services authenticate using the Client Credentials flow. Call /v2/oauth/token with your client_id and client_secret to receive a session_id, then include it as an X-Session-Id header on all subsequent API calls

Examples

Python Example

import requests            

  URL = "https://api.innerspace.io"                                                                                                              
   
  def get_session_id():                                                                                                                                    
      response = requests.post(                          
          url=f"{URL}/v2/oauth/token",
          json={                                                                                                                                           
              "client_id": "Your Client ID",
              "client_secret": "Your Client Secret",                                                                                                       
              "audience": "https://global-config.innerspace.io",
          },
          headers={"Content-Type": "application/json"},
      )                                                                                                                                                    
      response.raise_for_status()
      return response.json()["session_id"]                                                                                                                 
                                                         

  sample_graphql = {
      "operationName": "sample_graphql",
      "variables": {},
      "query": """                                                                                                                                         
          query sample_graphql {
              BUILDING_INSIGHTS(                                                                                                                           
                  where: {                               
                      DATE_PARTITION: {_eq: 20250501},
                      BUILDING_ID: {_eq: 71},
                      GRANULARITY: {_eq: "PT1H"},                                                                                                          
                      GROUP_ID: {_eq: "all-e707b3a8-0732-49ae-9156-13ff1138540e"},
                      SITE_ID: {_eq: 900000222}                                                                                                            
                  },                                                                                                                                       
                  order_by: {DATE_TIME_START: desc}
              ) {                                                                                                                                          
                  BUILDING_ID                            
                  DATE_TIME_START
                  OCCUPANCY_MEAN
                  GRANULARITY
                  GROUP_ID
                  SITE_ID                                                                                                                                  
              }
          }                                                                                                                                                
      """,                                               
  }

  session_id = get_session_id()
  response = requests.post(
      url=f"{URL}/v2/api",
      json=sample_graphql,
      headers={"X-Session-Id": session_id},                                                                                                                
  )
                                                                                                                                                           
  # re-authenticate if session expired and retry once                                                                                                      
  if response.status_code == 401:
      session_id = get_session_id()                                                                                                                        
      response = requests.post(                          
          url=f"{URL}/v2/api",
          json=sample_graphql,                                                                                                                             
          headers={"X-Session-Id": session_id},
      )                                                                                                                                                    
                                                         
  response.raise_for_status()
  print(response.json())

CURL Example

# Retrieve session ID       
  curl --request POST \
       --url https://api.innerspace.io/v2/oauth/token \                                                                                               
       --header 'Content-Type: application/json' \                                                                                                         
       --data '{"client_id":"Your Client ID","client_secret":"Your Client Secret","audience":"https://global-config.innerspace.io"}'                       
                                                                                                                                                           
  # Call API using session ID                            
  curl --request POST \                                                                                                                                    
       --url https://api.innerspace.io/v2/api \     
       --header 'Content-Type: application/json' \
       --header 'X-Session-Id: <session_id>' \                                                                                                             
       --data '{"operationName":"sample_graphql","variables":{},"query":"query sample_graphql { BUILDING_INSIGHTS(where: {DATE_PARTITION: {_eq: 20250501}, 
  BUILDING_ID: {_eq: 71}, GRANULARITY: {_eq: \"PT1H\"}, GROUP_ID: {_eq: \"all-e707b3a8-0732-49ae-9156-13ff1138540e\"}, SITE_ID: {_eq: 900000222}},         
  order_by: {DATE_TIME_START: desc}) { BUILDING_ID\n DATE_TIME_START\n OCCUPANCY_MEAN\n GRANULARITY\n GROUP_ID\n SITE_ID\n }\n }"}'

Python GraphQL

import sys
import logging
import requests
from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport
from gql.transport.aiohttp import log as requests_logger

requests_logger.setLevel(logging.WARNING)

API_BASE_URL = "https://api.innerspace.io"
AUDIENCE = "https://global-config.innerspace.io"
CLIENT_ID = "Your Client ID"
CLIENT_SECRET = "Your Client Secret"


def get_session_id():
    response = requests.post(
        url=f"{API_BASE_URL}/v2/oauth/token",
        json={
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "audience": AUDIENCE,
        },
    )
    response.raise_for_status()
    return response.json()["session_id"]


def main(argv):
    session_id = get_session_id()

    transport = AIOHTTPTransport(
        url=f"{API_BASE_URL}/v2/api",
        headers={"X-Session-Id": session_id},
    )

    client = Client(transport=transport, fetch_schema_from_transport=False)

    query = """
        query sample_graphql {
            BUILDING_INSIGHTS(
                where: {
                      DATE_PARTITION: {_eq: 20250501},                                                                                                     
                      BUILDING_ID: {_eq: 71},
                      GRANULARITY: {_eq: "PT1H"},                                                                                                          
                      GROUP_ID: {_eq: "00000000-0000-0000-0000-000000000000"},
                      SITE_ID: {_eq: 900000222} 
                },
                order_by: {DATE_TIME_START: desc}
            ) {
                  BUILDING_ID                                                                                                                              
                  DATE_TIME_START
                  OCCUPANCY_MEAN                                                                                                                           
                  GRANULARITY                            
                  GROUP_ID
                  SITE_ID
            }
        }
    """
    print(client.execute(gql(query)))


if __name__ == "__main__":
    main(sys.argv)