Authentication
Create an API key in the workspace used by your integration. Customer keys retrieve forecasts; producer keys submit them. Keep the key secret.
Create an API key
Create keys from the API key page in the workspace used by your integration:
- Get Forecasts: Customer API keys
- Submit Forecasts: Producer API keys
Choose a descriptive name such as production-ingestion or forecast-pipeline-staging, then select an expiration of 30, 90, or 365 days. Non-expiring keys are supported but should be reserved for integrations with an established rotation process.
The secret is shown only once after creation. Copy it immediately and store it in a secret manager.
Authenticate a request
Send the secret in the Authorization header using the Bearer scheme:
curl 'https://telescope.energy/api/v2/customer/catalog' \
-H "Authorization: Bearer $TELESCOPE_API_KEY"
Do not send API keys as query parameters, request-body fields, or browser-visible environment variables.
Key profiles and scopes
Scopes are assigned automatically from the selected workspace profile.
| Profile | Scopes | Intended use |
|---|---|---|
| Customer | catalog:read, forecasts:read | Discover products and retrieve current or historical forecasts. |
| Producer | catalog:read, submissions:read, submissions:write | Discover available definitions, submit forecasts, and inspect accepted submissions. |
Using a valid key without the required scope returns 403 INSUFFICIENT_SCOPE. Creating a profile-specific key also requires active access to its corresponding Telescope workspace.
Store keys securely
- Keep secrets in a server-side secret manager or encrypted CI/CD variable.
- Never commit a key to source control, logs, examples, tickets, or screenshots.
- Use separate keys for development, staging, and production.
- Give each running integration its own key so it can be revoked independently.
- Avoid calling authenticated endpoints directly from a public browser application.
Example local configuration:
export TELESCOPE_API_KEY="<YOUR_API_KEY>"
Rotate or revoke a key
Create a replacement key before revoking the old one:
- Create a new key with the same profile.
- Deploy the new secret to the integration.
- Confirm successful requests with the new key.
- Revoke the old key from the workspace API key page.
Revocation is immediate. Requests using an expired, revoked, malformed, or unsupported key return 401.
Authentication errors
401 means no valid key was supplied. Check for an expired, revoked or incorrectly copied key. 403 INSUFFICIENT_SCOPE means you need a key from the appropriate workspace. See Troubleshooting for recovery steps and retain the requestId when contacting support.