Contact [email protected] for API credentials.

This repository contains more extensive examples for interacting with the API, as well as tips on best practices and troubleshooting.

All API endpoints are authenticated using OAuth 2.0 or API Keys , see below. API credentials are provided as Client Credential Grant.

M2M Client Authentication (OAuth 2.0)

1. Get an access token

Request an access token from the Authenticate endpoint, providing your client ID and secret:

curl --request POST \
  --url https://armoredthings.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data-raw '{
    "client_id":"<CLIENT ID>",
    "client_secret":"<CLIENT SECRET>",
    "audience":"api.lambentspaces.com",
    "grant_type":"client_credentials"
  }'

Response

{
  "access_token": "<TOKEN>",
  "token_type": "Bearer"
}

2. Query the Level Occupancy API

Query the Level Occupancy v1 endpoint by providing your access token in the Authorization header:

curl --request GET \
  --url https://prod-api-ag.lambentspaces.app/analyze/v1/occupancy/level \
  --header 'Authorization: Bearer <TOKEN>'

API Keys

As an alternative to OAuth 2.0, you can authenticate with an API key. An API key is a single credential sent with each request, with no token request first. That makes it a good fit for scheduled jobs, scripts and server-to-server integrations.

1. Getting an API key

Contact [email protected] to request an API key. Each key:

is issued for your organization, and can read only the buildings and data it has been granted;
has an expiration date, set when the key is issued;
is shown only once, when it is issued. Lambent cannot retrieve it again, so store it straight away in a secrets manager or other secure store.

API keys are 64 characters long and begin with lsk_.

2. Using an API key

Send the key in the X-API-Key header:

curl --request GET \
  --url 'https://prod-api-ag.lambentspaces.app/analyze/v1/occupancy/level?start=-1d&resolution=1h' \
  --header 'accept: application/json' \
  --header 'X-API-Key: lsk_YOUR_API_KEY'

import os
import requests

response = requests.get(
    "https://prod-api-ag.lambentspaces.app/analyze/v1/occupancy/level",
    params={"start": "-1d", "resolution": "1h"},
    headers={"X-API-Key": os.environ["LAMBENT_API_KEY"]},
    timeout=60,
)
response.raise_for_status()

Send either an X-API-Key header or an Authorization: Bearer header, not both. A request with both is rejected with 400. You don't need to pass tenant_id; it defaults to your organization.

Replacing and revoking keys

Several keys can be valid at the same time, so you can switch keys without downtime:

Ask Lambent for an additional key, with its own expiration date.
Update your systems to use the new key.
Ask Lambent to revoke the old key, or let it expire.

Do this well before a key's expiration date.

If a key may have been exposed, ask Lambent to rotate it instead. Rotating issues a replacement key with the same expiration date and revokes the old key immediately, so anything still using the old key fails until it is updated. A revoked key stops working within a minute.

Errors

Status	Response	What to do
`401`	`Invalid API key`	The key isn't recognised or has been revoked. Check that the full key was sent, or request a new one.
`401`	`API key has expired`	The key is past its expiration date. Switch to a newer key.
`403`	Not authorized	The key is valid but doesn't grant the data requested, for example a building it hasn't been granted. Contact Lambent to change its access.
`503`	`Unable to verify API key`	The key couldn't be verified right now and may well be valid. Retry after the number of seconds in the `Retry-After` header.

Keeping keys secure

Keep API keys on servers only, never in browser or mobile app code.
Never commit keys to source control. Load them from environment variables or a secrets manager.
Use a separate key per system, so each can be replaced or revoked on its own.
If a key may have been exposed, ask Lambent to rotate it immediately, or to revoke it if you no longer need it.