---
title: "Authentication"
canonical_url: https://docs.zvid.io/docs/authentication/
source: docs/authentication.md
content_revision: 6338386a1dd87e4a
---

# 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](https://app.zvid.io/api-keys) of the Zvid dashboard:

1. Log in to your Zvid account at [app.zvid.io](https://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:

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

```javascript
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:

```text
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. The client can store a
refresh credential to renew access without another sign-in. Revoke access or
disconnect the client when it is no longer needed.

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?

For setup and the validate → estimate → render workflow in an AI client, see
[AI assistants](https://docs.zvid.io/docs/ai-assistants/). For supported integration choices, see
[Integrations](https://docs.zvid.io/docs/integrations/).

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 us at [https://zvid.io/contact](https://zvid.io/contact).