Authentication

Zvid has two authentication methods. Which one you use depends on how you connect:

Method	Use it for
API key (zvid_… in the x-api-key header)	Direct REST API calls, SDKs, server-to-server automations, and the Zvid n8n action and trigger nodes
OAuth — sign in with your Zvid account	AI agents connecting through the hosted MCP endpoint https://mcp.zvid.io/mcp — Claude Code, Codex, and the one-click n8n AI-agent workflow

Method 1 — API keys

Programmatic Zvid API access uses API keys. Include your key in the x-api-key header on API-key compatible endpoints such as render submission, job lookup, profile lookup, credits, and API-key management.

Creating an API Key

Create API keys on the API Keys page of the Zvid dashboard:

1. Log in to your Zvid account at app.zvid.io.
2. Open API Keys.
3. Click Create API Key.
4. Enter a descriptive name, such as Production Server.
5. Copy the generated key immediately.

Important

The full API key is shown only once. If you lose it, revoke the old key and create a new one.

Using API Keys

Send the API key in the x-api-key header:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: zvid_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

const response = await fetch("https://api.zvid.io/api/user/profile", {
  headers: {
    "x-api-key":
      "zvid_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  },
});

const data = await response.json();
console.log(data);

API Key Format

Zvid API keys use this format:

zvid_<64-character-hexadecimal-string>

• zvid_: Zvid production key prefix.
• 64-character-hexadecimal-string: Secret key material using a-f and 0-9.

Security Recommendations

• Store API keys in server-side environment variables or a secrets manager.
• Do not expose API keys in browser code, mobile apps, public repos, logs, or support screenshots.
• Use separate keys for production and development.
• Revoke keys that are unused or suspected to be exposed.

Method 2 — OAuth sign-in for AI agents (MCP)

AI agents connect to Zvid through the hosted MCP endpoint https://mcp.zvid.io/mcp. Instead of pasting an API key, you sign in with your Zvid account: the endpoint publishes OAuth discovery metadata, uses authorization code + PKCE with the single scope zvid:mcp, and issues short-lived access tokens with rotating refresh tokens. Tokens are revocable and expire on their own, so nothing long-lived is stored in the client.

This is the method used by:

• Claude Code — claude mcp add --transport http zvid https://mcp.zvid.io/mcp, then claude mcp login zvid.
• OpenAI Codex — register https://mcp.zvid.io/mcp with auth = "oauth", then authenticate from MCP settings.
• n8n AI-agent workflow — the Zvid MCP Tools node uses n8n's built-in MCP OAuth2 API credential; you sign in from the node, with dynamic client registration enabled.

Two API-key fallbacks exist for MCP: the hosted endpoint also accepts an API key in the X-Api-Key header for clients that cannot run an OAuth flow, and the local/self-hosted stdio server (@zvid/mcp on npm) is API-key only.

Which method does my n8n workflow use?

• Zvid action node and Zvid Trigger → the Zvid API credential with an API key (method 1).
• Zvid MCP Tools node in the AI-agent workflow → n8n's built-in MCP OAuth2 API credential with OAuth sign-in (method 2).

A workflow that combines both needs both credentials.

Need Help?

If authentication fails:

1. API key: verify the key value is correct, confirm the header name is exactly x-api-key, and check that the key has not been revoked.
2. OAuth: sign out and reconnect from your MCP client to obtain a fresh token, and confirm the endpoint is exactly https://mcp.zvid.io/mcp.
3. Contact help@zvid.io.