Docs navigation
Reference
Weather MCP
Agents
Authentication
Every REST request sends an HTTP Bearer token, except /.well-known/deprecations, /v1/health, and /v1/status. The same key works for the Weather MCP.
Send Authorization: Bearer <key> on each request (RFC 6750). Keys come in two prefixes:
sw_live_*— production trafficsw_test_*— CI and local development
Create, rotate, and revoke keys in the dashboard. Need an account first? Create one. Your agent can create a key with create_api_key after you approve it once in the browser. See Built for agents.
Trial keys
An agent with no human present can create a trial key with no account (npx -y @smarterweather/mcp-onboarding@latest trial). You need Node.js 22 or later. It works on a few routes for a short time and a human can claim it into a free account to keep it. The limits are on the quickstart; how trial keys work. /v1/catalog spends no trial call, but still needs a key.
Keep keys on the server
A key is a server-side secret. Keep it in .env or your secret store, call the API from your backend, and never ship the key in a browser bundle or mobile app. The API does not send CORS headers for third-party origins, so browser calls from your site fail by design. For curl with the key in .env, use the quickstart's loader, which reads only the key and never runs the file as shell.
If a key leaks
Revoke it in the dashboard and create a new one. If GitHub secret scanning finds a live key in a public repository, we revoke it for you. See Leaked API keys.
Scopes
Each key carries scopes: api for the REST API and mcp for the Weather MCP. New keys get both by default. A key without the scope a request needs gets a 403 problem of type forbidden, with error="insufficient_scope" and the missing scope in its WWW-Authenticate header.
curl "https://api.smarterweather.com/v1/weather?lat=42.3601&lon=-71.0589" \
-H "Authorization: Bearer ${SMARTERWEATHER_API_KEY:?set SMARTERWEATHER_API_KEY first, see developers.smarterweather.com/quickstart}"// save as sample.mjs; run: node --env-file=.env sample.mjs (Node 20.6+, ESM top-level await)
const res = await fetch(
"https://api.smarterweather.com/v1/weather?lat=42.3601&lon=-71.0589",
{ headers: { Authorization: `Bearer ${process.env.SMARTERWEATHER_API_KEY}` } },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(JSON.stringify(data, null, 2));# pip install requests python-dotenv
import os, sys, requests
from dotenv import load_dotenv
load_dotenv(".env") # ./.env in the current directory; variables already set are kept
r = requests.get(
"https://api.smarterweather.com/v1/weather",
params={"lat":"42.3601","lon":"-71.0589"},
headers={"Authorization": f"Bearer {os.environ['SMARTERWEATHER_API_KEY']}"},
)
if not r.ok:
sys.exit(f"{r.status_code} {r.text}")
data = r.json()
print(data)package main
import (
"fmt"
"io"
"log"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", "https://api.smarterweather.com/v1/weather?lat=42.3601&lon=-71.0589", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("SMARTERWEATHER_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
log.Fatal(err)
}
if res.StatusCode < 200 || res.StatusCode > 299 {
log.Fatalf("%s %s", res.Status, body)
}
fmt.Println(string(body))
}