> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamagicverify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Secure your API requests with workspace-scoped API keys

## Overview

The MediaMagic API uses API keys for authentication. Each API key is workspace-scoped, so it can only access resources within its associated workspace — you never send a workspace ID in the request body. The workspace is derived from the key.

Live keys are prefixed `sk_live_` and sandbox keys are prefixed `sk_test_`. Both use the same base URL and paths; the prefix alone selects the environment. See the [Sandbox Guide](/reference/sandbox) for sandbox behavior.

## Creating an API key

<Steps>
  <Step title="Open the control plane">
    Log in to the MediaMagic control plane at `https://mediamagic-lite.northell.io`
  </Step>

  <Step title="Navigate to API keys">
    Go to **Settings** → **API Keys** → **Generate New Key**
  </Step>

  <Step title="Copy your key">
    The API key will be displayed once. Copy it immediately — you won't be able to see it again.
  </Step>

  <Step title="Store securely">
    Store your API key in your application's environment variables, secrets manager, or key vault.
  </Step>
</Steps>

## Using your API key

Include your API key in the `X-API-Key` header of every request:

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions
```

<CodeGroup>
  ```python requests theme={null}
  import requests

  headers = {
      "X-API-Key": "your-api-key-here",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions",
      headers=headers,
      json={"assets": [...]}
  )
  ```

  ```javascript fetch theme={null}
  const headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
  };

  const response = await fetch(
    "https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions",
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify({ assets: [...] })
    }
  );
  ```

  ```typescript axios theme={null}
  import axios from "axios";

  const apiKey = "your-api-key-here";

  const response = await axios.post(
    "https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions",
    { assets: [...] },
    {
      headers: {
        "X-API-Key": apiKey,
        "Content-Type": "application/json"
      }
    }
  );
  ```
</CodeGroup>

## Security best practices

<Warning>
  Never hardcode API keys in your application code or commit them to version control. Always use environment variables or a secrets manager.
</Warning>

* Store API keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, Azure Key Vault)
* Rotate API keys regularly — we recommend monthly rotation
* Use different API keys for different environments (development, staging, production)
* Monitor API key usage in the control plane to detect suspicious activity
* Revoke API keys immediately if you suspect they've been compromised

## Authentication errors

If your API key is missing, invalid, expired, or revoked, you'll receive a `401 Unauthorized` response with a `detail` message:

```json theme={null}
{
  "detail": "Invalid API key"
}
```

The `detail` message tells you exactly what went wrong. Common messages include:

* `Missing X-API-Key header` — no key was sent
* `Invalid API key` — the key is not recognized
* `This API key has expired`
* `This API key has been revoked`

Check that:

* The header name is exactly `X-API-Key` (case-sensitive)
* Your API key is correct and has not expired or been revoked
* You are using a key for the workspace whose resources you are trying to access

## Rate limiting

API requests are rate limited per API key. See [Rate Limiting](/reference/rate-limiting) for details.