Skip to content

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.

Key Scope

A key can be granted whole building owners, or only individual buildings within them. A building-scoped key sees just its own buildings everywhere: GET /v1/building_owners lists only the owners it can reach, /buildings returns only its buildings, and /status and /search cover only those buildings rather than the whole portfolio. Owner-level changes - renaming or deleting a building owner, or creating a new building - always require access to the whole building owner and return 403 otherwise.

Owner-wide search is limited to keys scoped to at most 100 individual buildings. Above that, search one building at a time via /buildings/{buildingId}/search.

Making Requests

Include the API key in every request:

curlbash
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.findable.ai/v1/building_owners
SDK (automatic)typescript
const client = new FindableClient({
  apiKey: 'YOUR_API_KEY', // pragma: allowlist secret
  buildingOwnerId: 'cust-456',
});

Error Responses

StatusMeaning
401Missing or invalid API key
403API 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.

POST/v1/building_owners/{buildingOwnerId}/sessions

Exchange a server-side API key for a short-lived token that is safe to pass to a browser.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner / customer ID
  • expires_innumberToken lifetime in seconds (60–86400). Default 3600. Minimum: 60. Maximum: 86400.

Request Body Example

{ "expires_in": 3600 }

Examples

curl -X POST https://api.findable.ai/v1/building_owners/OWNER_ID/sessions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'
  • 200Session created
  • 401Missing or invalid API key

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • tokenstringShort-lived session token
  • expires_atstring (ISO 8601)Time at which the session token expires

Response

{
  "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/v1/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