Authentication

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 for sandbox behavior.

Creating an API key

Open the control plane

Navigate to API keys

Go to Settings → API Keys → Generate New Key

Copy your key

The API key will be displayed once. Copy it immediately — you won’t be able to see it again.

Store securely

Store your API key in your application’s environment variables, secrets manager, or key vault.

Using your API key

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

curl -H "X-API-Key: your-api-key-here" \
  https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions

import requests

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

response = requests.post(
    "https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions",
    headers=headers,
    json={"assets": [...]}
)

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

const response = await fetch(
  "https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify({ assets: [...] })
  }
);

import axios from "axios";

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

const response = await axios.post(
  "https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions",
  { assets: [...] },
  {
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json"
    }
  }
);

Security best practices

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

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:

{
  "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 for details.

Getting Started

Core Concepts

Guides

Reference

API Endpoints

Overview

Creating an API key

Using your API key

Security best practices

Authentication errors

Rate limiting

​Overview

​Creating an API key

​Using your API key

​Security best practices

​Authentication errors

​Rate limiting

Overview

Creating an API key

Using your API key

Security best practices

Authentication errors

Rate limiting