Runtime API authentication

Category: Developer. Status: Normative.

Published runtime requests use a Vertcie public API key. The key grants only supported runtime operations; it is not a user login, administrative credential, or storage credential.

Send the key

Preferred transport:

GET /api/get-published-file?publishedFileId=PUBLISHED_FILE_ID HTTP/1.1
Host: VERTCIE_HOST
x-vertcie-key: VERTCIE_PUBLIC_API_KEY
Origin: https://app.example.com

Some compatibility calls may accept apiKey in the query string. New integrations must use x-vertcie-key; query parameters can leak through browser history, analytics, logs, screenshots, and referrers.

The same header authorizes active and exact Runtime manifest requests. Revision selection does not change or broaden key permissions:

GET /api/runtime/publications/PUBLISHED_FILE_ID/revisions/4/manifests/expanders HTTP/1.1
Host: VERTCIE_HOST
x-vertcie-key: VERTCIE_PUBLIC_API_KEY
Origin: https://app.example.com

Browser use

A browser runtime key is intentionally public but must be restricted to the approved application origins and the minimum runtime capabilities. Send the browser's real Origin. Do not attempt to hide a browser key through obfuscation or use it for privileged operations.

Server use

Load the key from the deployment environment and send it only to the configured Vertcie host:

const response = await fetch(
  `${process.env.VERTCIE_API_URL}/api/get-published-file?publishedFileId=${encodeURIComponent(publishedFileId)}`,
  { headers: { "x-vertcie-key": process.env.VERTCIE_API_KEY! } },
);

Never log the key or forward it to an arbitrary URL supplied by a user.

Rotation

1. Issue a replacement key with the intended origins.
2. Deploy the replacement.
3. Verify representative runtime traffic.
4. Revoke the previous key.

Authentication errors

Do not bypass a failed API request by accessing implementation storage directly.