🔐 Authentication
Skycaster uses API key-based authentication. Every request must include your API key, and the account behind it needs an active subscription.
🧾 How It Works
After subscribing, sign in to the Skycaster Dashboard and create a key under Profile → API Keys. The dashboard shows each key’s request count, rate-limited count and last-used time. Keys are shown once when created — store them safely.
🌐 Base URL
https://www.skycaster.tv/api/public/v1/All API endpoints are relative to this base URL.
✅ Sending Your API Key
Use one of these. If more than one is present, the query parameter wins, then Authorization, then x-api-key.
🧾 Authorization Header (recommended)
curl 'https://www.skycaster.tv/api/public/v1/weather' \
-H 'Authorization: Bearer YOUR_API_KEY_HERE'🧾 x-api-key Header
curl 'https://www.skycaster.tv/api/public/v1/weather' \
-H 'x-api-key: YOUR_API_KEY_HERE'🔗 Query Parameter
curl 'https://www.skycaster.tv/api/public/v1/weather?apiKey=YOUR_API_KEY_HERE'Headers are preferred for production: query strings can end up in logs and browser history.
🚫 Errors
Every error response has the same shape:
{ "error": "Invalid API key" }The API key is checked before any other parameter, so a request with a bad key always gets 401/403, never a parameter error.
| Status | error | Meaning |
|---|---|---|
| 401 | Missing API key | No key in the query string or headers. |
| 401 | Invalid API key | The key doesn’t exist or was revoked. |
| 403 | No active subscription | The account has no active or trialing subscription. |
| 429 | Rate limit exceeded | Too many requests for your plan (see below). |
| 500 | Internal server error | Something went wrong on our side — retry shortly. |
Endpoint-specific 400 errors are listed on each endpoint page.
⏱️ Rate Limits
Limits apply per API key, over a sliding 60-second window:
| Plan | Requests per minute |
|---|---|
| Skycaster Station | 10 |
| Skycaster Regional | 30 |
| Skycaster Global | 60 |
Responses are cached on our side (current weather 60 s, hourly forecast 5 min, daily forecast 15 min), so polling faster than that returns the same data. Publishing new settings on the Weather Data page clears the cache immediately.
🛡️ Security Best Practices
- Keep your API key secret — never expose it in frontend code or public repositories.
- Make requests from a secure, server-side environment whenever possible.
- Revoke a key from the dashboard if it may have leaked; it stops working immediately.
- Store keys in environment variables or a secrets manager.
📞 Need Assistance?
If you have questions or need support, email us at support@skycaster.tv.