Authentication

All Partner API requests require an API key passed in the x-api-key header.

API Key

API keys are provisioned by your Findable representative. Each key is scoped to a partner organisation and determines which building owners you can access.

Making Requests

Include the API key in every request:

curlbash

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.findable.ai/building_owners

SDK (automatic)typescript

const client = new FindableClient({
  apiKey: 'YOUR_API_KEY', // pragma: allowlist secret
  buildingOwnerId: 'cust-456',
});

Error Responses

Status	Meaning
`401`	Missing or invalid API key
`403`	API key does not have access to the requested resource

Session Tokens

Session tokens let you authenticate from client-side code without exposing your API key. Your server exchanges its API key for a short-lived, scoped token and passes it to the browser.

1. Server-side: create a session tokenbash

curl -X POST https://api.findable.ai/building_owners/OWNER_ID/sessions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'
# => { "token": "ft_...", "expires_at": "2026-03-20T13:00:00.000Z" }

2. Client-side: use the session tokenbash

curl -H "Authorization: Bearer ft_..." \
  https://api.findable.ai/building_owners/OWNER_ID/buildings

Tokens are scoped to a single building owner and expire after the specified duration (default 1 hour, max 24 hours). See the SDK docs for programmatic usage.

Security Best Practices

Keep your keys secure

Never expose API keys in client-side code. Use session tokens for browser-based access.
Keep session token lifetimes short (the default 1 hour is recommended).
Rotate keys periodically via your Findable representative.
Use separate keys for development and production.