Authenticate Requests to the Moonshadow API

Moonshadow uses Bearer token authentication. Learn how to generate API keys, pass them in requests, manage scopes, and rotate keys.

Moonshadow authenticates every API request with a Bearer token. You generate API keys from the dashboard, pass them in the Authorization header, and control access with scopes. This page explains the full lifecycle: creating a key, using it in code, choosing the right permissions, and rotating it when needed.

Get an API Key

1. Sign in to the Moonshadow dashboard.
2. Open Settings > API Keys.
3. Click Generate Key.
4. Enter a descriptive name (for example, “production-deploy” or “ci-runner”).
5. Select the scopes you need (see the scopes table below).
6. Copy the token immediately. Moonshadow shows it only once.

Treat API keys like passwords. Do not expose them in client-side code, public repositories, or browser extensions.

Pass the API Key in Requests

Include the key in the Authorization header as a Bearer token on every call to https://api.moonshadow.dev/v1.

cURL

curl -X GET "https://api.moonshadow.dev/v1/workspaces" \
  -H "Authorization: Bearer ms_live_abcdefghijklmnopqrstuvwxyz"

If the key is missing, expired, or invalid, Moonshadow returns:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

Scopes

Scopes restrict what an API key can do. Choose the minimum set required for your integration.

Scope	Permissions
read	List and retrieve workspaces, integrations, users, and events.
write	Create, update, and delete resources within allowed workspaces.
admin	Manage workspace membership, billing, and API keys. Full control.

A key with write scope implicitly includes read. A key with admin scope includes read and write. You can assign scopes per workspace if you generate the key from a workspace settings page.

Key Rotation

Rotate keys regularly to limit exposure from leaks or employee offboarding.

1. In the dashboard, go to Settings > API Keys.
2. Click Rotate next to the key you want to replace.
3. Moonshadow creates a new key with the same scopes and deactivates the old one after a 24-hour grace period.
4. Update your environment variables and redeploy during the grace period.

After the grace period expires, requests with the old key return 401 Unauthorized with no recovery path.

Environment Keys

Moonshadow supports separate API keys for production and staging environments. Prefixes help you tell them apart:

• Production keys start with ms_live_.
• Staging keys start with ms_test_.

Staging keys target a sandbox workspace with isolated data and lower rate limits. Use staging keys in CI pipelines and local development to avoid affecting live workspaces.

Store the active key in an environment variable such as MOONSHADOW_API_KEY and load it at runtime. This lets you switch environments without changing code.

Security Best Practices

• Never commit API keys to version control. Use .env files and secret managers.
• Use read-only keys for monitoring dashboards and write keys for automation services.
• Rotate keys every 90 days or immediately after a team member leaves.
• Restrict keys to the smallest set of workspaces and scopes possible.