Skip to content
Docs navigation

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 traffic
  • sw_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))
}