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

# Authentication

> Learn how to authenticate your API requests

## API Keys

All API requests (except `/health`) require authentication using an API key. API keys are tied to your VibePeak account and grant access based on your subscription plan.

### Getting an API Key

1. Log in to your [VibePeak Dashboard](https://app.vibepeak.ai)
2. Navigate to **Settings** → **API**
3. Click **Create API Key**
4. Give your key a descriptive name (e.g., "Production", "Development")
5. Copy and securely store your key

<Warning>
  **Your API key is only shown once.** Store it immediately in a secure location like a password manager or environment variable. If you lose it, you'll need to create a new one.
</Warning>

### API Key Format

VibePeak API keys follow this format:

```
vpk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
```

* `vpk_live_` - Prefix identifying it as a VibePeak **live** API key
* `aBcDeFgHiJkLmNoPqRsTuVwXyZ123456` - Random unique identifier

### Live vs. Test Keys

Every key carries a prefix that fixes its mode for the life of the key:

| Prefix      | Mode | Behavior                                                                         |
| ----------- | ---- | -------------------------------------------------------------------------------- |
| `vpk_live_` | Live | Charges credits and runs the real generation pipeline, returning your real video |
| `vpk_test_` | Test | A free sandbox — charges nothing and returns a watermarked sample video          |

A test-mode key (`vpk_test_`) lets you build and verify your integration end to end without spending credits. It exercises the identical request, validation, async lifecycle, and signed-webhook surface as a live key.

<Info>
  See [Test Mode](/concepts/test-mode) for the full sandbox model, the `test_scenario` parameter, and the `livemode` response field.
</Info>

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer vpk_live_xxxxx
```

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.vibepeak.ai/v1/tasks/task_abc123 \
    -H "Authorization: Bearer vpk_live_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.vibepeak.ai/v1/tasks/task_abc123', {
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx',
    },
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.vibepeak.ai/v1/tasks/task_abc123',
      headers={'Authorization': 'Bearer vpk_live_xxxxx'}
  )
  ```
</CodeGroup>

## Authentication Errors

| Error Code        | HTTP Status | Description                               |
| ----------------- | ----------- | ----------------------------------------- |
| `MISSING_API_KEY` | 401         | No API key provided in the request        |
| `INVALID_API_KEY` | 401         | The API key is malformed or doesn't exist |
| `API_KEY_REVOKED` | 401         | The API key has been revoked              |
| `API_KEY_EXPIRED` | 401         | The API key has expired                   |
| `PLAN_REQUIRED`   | 403         | Your plan doesn't include API access      |

### Example Error Response

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "request_id": "req_abc123xyz"
  }
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose keys in client-side code" icon="eye-slash">
    API keys should only be used in server-side code. Never include them in:

    * JavaScript running in the browser
    * Mobile app code
    * Public repositories
    * Frontend environment variables
  </Accordion>

  <Accordion title="Use environment variables" icon="terminal">
    Store your API key in environment variables rather than hardcoding:

    ```bash theme={null}
    # .env file (never commit this!)
    VIBEPEAK_API_KEY=vpk_live_xxxxx
    ```

    ```javascript theme={null}
    // Node.js
    const apiKey = process.env.VIBEPEAK_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotate keys periodically" icon="rotate">
    Rotate your API keys periodically and immediately if you suspect compromise.
    You can create a new key and revoke the old one from your dashboard.
  </Accordion>

  <Accordion title="Use separate keys per environment" icon="code-branch">
    Create separate API keys for development and production.
    This limits the impact if a key is compromised.
  </Accordion>
</AccordionGroup>

## Managing API Keys

### Viewing Keys

From your [API settings](https://app.vibepeak.ai/settings/api), you can see:

* Key name and creation date
* Key prefix (first 8 characters)
* Last used timestamp
* Revocation status

<Note>
  For security, the full API key is never shown after creation.
</Note>

### Revoking Keys

To revoke an API key:

1. Go to **Settings** → **API**
2. Find the key you want to revoke
3. Click the **Revoke** button
4. Confirm the action

Revoked keys immediately stop working. Any requests using them will receive a `401` error.

## Plan Requirements

API access requires a **Plus**, **Pro**, **Max**, or **Enterprise** plan.

| Plan       | API Access | Concurrent Tasks |
| ---------- | ---------- | ---------------- |
| Plus       | ✅          | 1                |
| Pro        | ✅          | 3                |
| Max        | ✅          | 5                |
| Enterprise | ✅          | Custom           |

If your account doesn't have a qualifying plan, you'll receive this error:

```json theme={null}
{
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "API access requires a Plus, Pro or Max plan. Please upgrade your subscription.",
    "details": {
      "current_plan": "none",
      "required_plans": ["Plus", "Pro", "Max"]
    }
  }
}
```

<Card title="Upgrade your plan" icon="arrow-up-right" href="https://app.vibepeak.ai/settings/billing">
  Get API access by upgrading to Plus or higher
</Card>