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

# Authentication

> Secure your API requests with API keys

## Overview

The Nouvel API uses **API keys** with Bearer token authentication. All requests must include your API key in the `Authorization` header.

<Warning>
  **Never expose your API keys in client-side code, version control, or public repositories.** API keys grant access to your account and quota.
</Warning>

## API Key Format

All Nouvel API keys use the prefix `nvl_` followed by a unique identifier:

```
nvl_xxxxxxxxxxxxxxxxxxxx
```

## Creating an API Key

<Steps>
  <Step title="Navigate to Settings">
    Log in to your Nouvel account and go to **Settings → API Keys**
  </Step>

  <Step title="Click 'Create API Key'">
    You can create up to **5 API keys** per account
  </Step>

  <Step title="Configure the key">
    * **Name**: A descriptive name for identification (e.g., "Production Server")
    * **Permissions**: Select which operations this key can perform
    * **Expiration**: Choose when the key should expire
  </Step>

  <Step title="Copy and store securely">
    The full API key is **only shown once** at creation. Store it in a secure location like a password manager or environment variable.
  </Step>
</Steps>

<Info>
  API keys are only available on **Scale** and **Business** plans. [Upgrade your plan](https://app.nouvel.ai/settings) to unlock API access.
</Info>

## Permissions

Each API key can have one or more of the following permissions. Choose only the permissions needed for each key to follow the principle of least privilege.

| Permission       | Description                | Grants Access To                                   |
| ---------------- | -------------------------- | -------------------------------------------------- |
| `generate`       | Create video ads           | `POST /api/v1/generate`                            |
| `projects:read`  | View project status & list | `GET /api/v1/jobs/{jobId}`, `GET /api/v1/projects` |
| `publish`        | Schedule & publish posts   | `POST /api/v1/publish`, `GET /api/v1/publish/{id}` |
| `analytics:read` | View analytics data        | `GET /api/v1/analytics`                            |
| `copilot:chat`   | Use AI copilot chat        | `POST /api/v1/copilot/chat`                        |

<Tip>
  For most use cases, you'll need at least `generate` and `projects:read` permissions to create videos and check their status.
</Tip>

## Expiration Options

Set an expiration date to automatically revoke keys after a certain period:

| Option          | Duration                        |
| --------------- | ------------------------------- |
| **7 days**      | Temporary testing/development   |
| **30 days**     | Short-term campaigns            |
| **90 days**     | Quarterly rotation              |
| **1 year**      | Annual rotation                 |
| **Never**       | No expiration (not recommended) |
| **Custom date** | Specific expiration date        |

<Warning>
  **Security best practice**: Set expiration dates and rotate keys regularly (every 90 days recommended). Never use "Never" for production keys.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header as a Bearer token:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.nouvel.ai/api/v1/generate \
    -H "Authorization: Bearer nvl_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com/products/protein-powder"],
      "variantCount": 1
    }'
  ```

  ```typescript TypeScript / Node.js theme={null}
  const NOUVEL_API_KEY = process.env.NOUVEL_API_KEY;

  const response = await fetch('https://app.nouvel.ai/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${NOUVEL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      urls: ['https://example.com/products/protein-powder'],
      variantCount: 1,
    }),
  });

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

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

  NOUVEL_API_KEY = os.environ.get('NOUVEL_API_KEY')

  response = requests.post(
      'https://app.nouvel.ai/api/v1/generate',
      headers={
          'Authorization': f'Bearer {NOUVEL_API_KEY}',
          'Content-Type': 'application/json',
      },
      json={
          'urls': ['https://example.com/products/protein-powder'],
          'variantCount': 1,
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store keys in environment variables">
    Never hardcode API keys in your source code. Use environment variables:

    ```bash .env theme={null}
    NOUVEL_API_KEY=nvl_xxxxxxxxxxxxxxxxxxxx
    ```

    Add `.env` to your `.gitignore` to prevent accidentally committing it.
  </Accordion>

  <Accordion title="Use separate keys for different environments">
    Create different API keys for development, staging, and production. This allows you to:

    * Identify which environment made a request
    * Revoke compromised keys without affecting other environments
    * Set different permissions per environment
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Set expiration dates and rotate keys every 90 days. When rotating:

    1. Create a new key
    2. Update your application to use the new key
    3. Verify the new key works
    4. Delete the old key
  </Accordion>

  <Accordion title="Grant minimum required permissions">
    Only grant permissions that are actually needed. For example:

    * **Read-only monitoring**: `projects:read`, `analytics:read`
    * **Video generation service**: `generate`, `projects:read`
    * **Publishing automation**: `publish`, `projects:read`
  </Accordion>

  <Accordion title="Monitor API key usage">
    Regularly check your API keys in the dashboard:

    * Review active keys and their last used date
    * Delete unused or forgotten keys
    * Check for unexpected usage patterns
  </Accordion>

  <Accordion title="Never expose keys client-side">
    **Never** include API keys in:

    * Frontend JavaScript code
    * Mobile app source code
    * Public GitHub repositories
    * Client-side API calls

    Always use a backend server or serverless function to make API calls.
  </Accordion>
</AccordionGroup>

## Error Responses

### Invalid API Key

```json theme={null}
{
  "error": "Unable to resolve user from API key"
}
```

**Status Code**: `401 Unauthorized`

**Causes**:

* API key is incorrect or malformed
* API key has been deleted or expired
* Missing `Authorization: Bearer` prefix

### Missing Permission

```json theme={null}
{
  "error": "This API key does not have the 'generate' permission"
}
```

**Status Code**: `403 Forbidden`

**Causes**:

* API key doesn't have the required permission for this endpoint
* Solution: Revoke this key and create a new one with the necessary permissions

### Plan Required

```json theme={null}
{
  "error": "API access requires a Scale or Business plan"
}
```

**Status Code**: `402 Payment Required`

**Causes**:

* Your account is on a Starter or Growth plan
* Solution: [Upgrade to Scale or Business](https://app.nouvel.ai/settings)

## Rate Limiting

All API keys are subject to rate limits:

* **60 requests per minute** per API key
* Rate limit resets every 60 seconds
* Exceeding the limit returns `429 Too Many Requests`

The response includes rate limit headers:

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1678901234
```

<Tip>
  Implement exponential backoff when you receive a `429` response. Wait for the time specified in `X-RateLimit-Reset` before retrying.
</Tip>

## Managing API Keys

### Viewing Active Keys

Navigate to **Settings → API Keys** to view all active keys:

* Key name and creation date
* Last used timestamp
* Permissions granted
* Expiration date

### Revoking a Key

Click the **Delete** button next to any key to immediately revoke it. This action is **permanent** and cannot be undone.

<Warning>
  Deleting a key immediately invalidates it. Any applications using that key will receive `401 Unauthorized` errors.
</Warning>

### Key Limit

You can create up to **5 API keys** per account. If you need more keys, delete unused ones or [contact support](mailto:support@nouvel.ai) for enterprise options.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/api-reference/quickstart">
    Generate your first video with the API
  </Card>

  <Card title="Generate Endpoint" icon="wand-magic-sparkles" href="/api-reference/generate">
    Learn about the video generation endpoint
  </Card>
</CardGroup>