Authentication

CortexVigil exposes a public REST API at https://staging-api.cortexvigil.com/api/v1/ (staging) and https://api.cortexvigil.com/api/v1/ (production). All non-public endpoints require an API key.

API Key Format

API keys are issued per External App and follow this format:

Keys are 32–48 characters of URL-safe base62 after the prefix.

Passing the Key

Every authenticated request MUST include the key in the X-API-Key header:

GET /api/v1/cameras HTTP/1.1
Host: staging-api.cortexvigil.com
X-API-Key: cvk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Do NOT pass the key as a query parameter — it will be rejected and may be logged by upstream proxies.

Where to Create a Key

1. Sign in to the CortexVigil web app.
2. Navigate to Admin → External Apps.
3. Click New App, give it a descriptive name (e.g., "Warehouse Integration").
4. Choose the scopes you need (see Scopes).
5. Optionally set a rate_limit_per_min (default: 60).
6. Copy the key shown ONCE on the success screen — it is not retrievable later.

Rotating Keys

To rotate a key, create a new app (or use the Rotate action on the existing app row), update your integration to the new key, then revoke the old key. There is no automatic expiry.

Revocation

Revoking a key from the Admin UI takes effect within ~60 seconds (Redis cache TTL).

Site Scope

Each External App is bound to a single site. The site_id is automatically applied as a filter to all queries — you cannot read or write data from another site even if you guess valid resource IDs.

MCP Authentication

MCP tool invocations use the same cvk_* key in the same X-API-Key header. The mcp:invoke scope is required in addition to any per-resource scopes the tool needs. See MCP Tools.