Authentication

Overview

The iClear 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"
    }
  }
);

Checking which workspace a key belongs to

API keys are scoped to a single workspace, and every endpoint takes that workspace implicitly from the key — no request names it. To find out which one you are holding, call GET /api/workspace:

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

{
  "workspaceId": "ws1...",
  "orgId": "org1...",
  "orgName": "Acme Media",
  "apiKeyName": "Production Integration"
}

Useful if your integration holds keys for several workspaces, or stores anything keyed by workspace. apiKeyName is the label given to the key when it was created, which helps tell keys apart in your own logs.

Prefer this over deriving an identifier from the key itself. The workspace id is stable across key rotation; a value derived from the key is not.

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

Checking which workspace a key belongs to

Security best practices

Authentication errors

Rate limiting

​Overview

​Creating an API key

​Using your API key

​Checking which workspace a key belongs to

​Security best practices

​Authentication errors

​Rate limiting

Overview

Creating an API key

Using your API key

Checking which workspace a key belongs to

Security best practices

Authentication errors

Rate limiting