> ## Documentation Index
> Fetch the complete documentation index at: https:// zenveil.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the ZenVeil API.

## API keys

ZenVeil uses API keys for all programmatic access. Keys look like:

```
zv_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
```

## Getting your API key

Your key is **emailed to you automatically** the first time you sign in at [zenveil.dev](https://zenveil.dev) — no extra navigation required. It is shown once and never stored in plaintext; treat it like a password.

**Lost your key?**
Go to **[Dashboard](https://zenveil.dev/dashboard) → Settings → API Key → Rotate Key**.
A new key is generated and emailed immediately. The old key is invalidated at the same instant.

## Using your API key

Pass the key in the `X-API-Key` header on every request:

```bash theme={null}
curl https://api.zenveil.dev/v1/scan/github \
  -H "X-API-Key: zvk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"repository": "owner/repo"}'
```

## Storing keys securely

**Never commit API keys to source control.** Use environment variables:

```bash theme={null}
# Set in your environment
export ZENVEIL_API_KEY="zvk_live_your_key_here"

# Reference in curl
curl https://api.zenveil.dev/v1/scan/github \
  -H "X-API-Key: $ZENVEIL_API_KEY" \
  ...
```

**In CI/CD**, use your platform's secret management:

```yaml theme={null}
# GitHub Actions
- name: Run security scan
  env:
    ZENVEIL_API_KEY: ${{ secrets.ZENVEIL_API_KEY }}
  run: zenveil scan repo .
```

## Key rotation

Rotate your API key if it's been exposed:

1. Go to **Settings → API Keys** in the dashboard
2. Click **Revoke** on the compromised key
3. Generate a new key
4. Update all integrations and CI/CD secrets

## Authentication errors

| Error                   | Cause                           | Fix                                                 |
| ----------------------- | ------------------------------- | --------------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid `X-API-Key`  | Check that the key is correct and the header is set |
| `403 Forbidden`         | Key exists but lacks permission | Check your plan — some features require Pro/Team    |
| `429 Too Many Requests` | Rate limit exceeded             | Wait and retry, or upgrade your plan                |

## Key scope

Each API key is tied to your account and subject to your plan's rate limits. Keys cannot be scoped to specific repositories or operations — one key grants access to all ZenVeil API endpoints.