> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://moonshadow.dev).
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.

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

## 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`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.moonshadow.dev/v1/workspaces" \
    -H "Authorization: Bearer ms_live_abcdefghijklmnopqrstuvwxyz"
  ```

  ```javascript JavaScript theme={null}
  fetch("https://api.moonshadow.dev/v1/workspaces", {
    headers: {
      Authorization: "Bearer ms_live_abcdefghijklmnopqrstuvwxyz",
    },
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.moonshadow.dev/v1/workspaces",
      headers={"Authorization": "Bearer ms_live_abcdefghijklmnopqrstuvwxyz"},
  )
  ```
</CodeGroup>

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

```json theme={null}
{
  "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.

<Warning>
  After the grace period expires, requests with the old key return `401 Unauthorized` with no recovery path.
</Warning>

## 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.

<Tip>
  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.
</Tip>

## 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.