Authentication

Every request to the Morphemeris API requires an API key. Keys are created in your dashboard.

API key format

Keys use the morphemeris_live_ prefix, which enables secret scanning tools (GitHub, GitGuardian) to detect accidentally committed keys:

morphemeris_live_abc123def456ghi789...

Sending your key

Pass your key in the Authorization header using the Bearer scheme:

curl "https://api.morphemeris.com/v1/positions?datetime=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

const res = await fetch(
  "https://api.morphemeris.com/v1/positions?datetime=2024-01-01T00:00:00Z",
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const data = await res.json();

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/positions",
    params={"datetime": "2024-01-01T00:00:00Z"},
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Alternatively, use the X-API-Key header:

curl "https://api.morphemeris.com/v1/positions?datetime=2024-01-01T00:00:00Z" \
  -H "X-API-Key: morphemeris_live_YOUR_KEY"

If both headers are present, Authorization takes precedence.

Key lifecycle

• Create — Set an optional expiration date and allowed origins
• Revoke — Immediately invalidated (may take up to 60 seconds to propagate)
• Rotate — Create a new key, update your integration, then revoke the old one
• Update origins — Modify allowed origins without revoking the key

All keys on an account share the same credit balance and rate limits.

Origin restrictions

Keys can optionally restrict which HTTP origins are allowed. This protects against browser-based abuse when using the API from frontend code.

Origin matching is exact string comparison against the full origin (e.g., https://myapp.com). Wildcard subdomains are not supported in v1.

Tip: Use an unrestricted key for your backend and a separate origin-restricted key for frontend code.

Browser-only keys

Any key you ship in browser JavaScript is public — anyone can read it out of your bundle. Origin restrictions alone do not protect such a key, because a request sent from outside a browser carries no Origin header at all and therefore takes the permissive server-to-server default.

Enabling Browser-only key on a key closes that path: a request with no Origin header is rejected with 403 origin_required instead of accepted.

Error responses

{
  "errors": [{
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "suggestion": "Check your key at morphemeris.com/dashboard/keys"
  }],
  "meta": { "request_id": "..." }
}