Authentication

Send your personal key in header X-API-Key only — never in the URL. Community after registration: 120 requests/day, free, no credit card. Loxone: key in Virtual Output header, not in PicoC source. Same header works for Home Assistant, Python, and any HTTP client.

SpotpriceAPI uses one simple rule: send your personal key in the HTTP header X-API-Key. No OAuth, no login per request. The key tells the server who you are and which features you may use.

Everyday example

Like a hotel key card: show it at the door (header), get the full breakfast (168 h forecast + Decision). No card? You still get in, but only the continental tray (48 h, no Decision).

When to use this page

Wiring a new script, EMS, or Loxone Virtual Output
Wondering why you only get 48 hours
Choosing between free Community and paid Professional

What you need

Free account at Register for Community tier
Key format: sf_live_… from your dashboard
Never put the key in the URL, git, or a screenshot

Step by step

1. Register with email and password. 2. Confirm email via the link — account activates as Community (free). 3. Copy sf_live_… from dashboard — shown once in plain text. 4. Every API call: add header X-API-Key: sf_live_YOUR_KEY. 5. Read access in each JSON response to see your effective tier. 6. Upgrade via portal subscription if you need higher rate limits.

Minimal example


curl https://api.spotpriceapi.com/v1/forecast \
  -H "X-API-Key: sf_live_YOUR_KEY"


{
  "access": {
    "tier": "community",
    "label": "Community",
    "full_version_available": true,
    "token_present": true,
    "token_valid": true
  }
}

Access tiers

Tier	Who	Horizon	Decision / Windows / Hours	Rate limit	Price
`basic`	No key or invalid key	48 h	Not available	60/hour per IP	Free
`community`	Registered key	168 h	Yes (fair use)	120/day per key	Free
`full_active` (Professional)	Paid Integrator	168 h	Yes	600/hour per account	€99/mo · €990/yr
`full_active` (OEM / enterprise)	Contract	168 h	Yes, white-label	3000/hour per account	On request

Telemetry (POST /v1/plant/telemetry) uses a separate softcap — see Rate limits.

Important `access` fields

Field	What it means
`tier`	`basic`, `community`, `full_trial`, or `full_active` (see `GET /v1/status` → `access_model`)
`label`	Human-readable name
`full_version_available`	`true` = 168 h + Decision features
`token_present`	Did you send a key header?
`token_valid`	Is that key real and active?

Common mistakes

Key in query string — ignored; you get Basic tier
Expecting HTTP 401 — Forecast/Decision return 200 with reduced data instead
Sharing one key in public Loxone config without Virtual Output — key must stay in VO header only
Losing the key — generate a new one in portal; old one stops working

Next steps

Getting Started — first call walkthrough
Rate limits — quotas per tier
Errors — not_available and friends
Decision API — needs Community+

Start with SpotpriceAPI

Live API status