> ## 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.

# Permissions

> Understanding API key permission scopes and access control

## Overview

Every Nouvel API key has a set of **permission scopes** that control which operations it can perform. Permissions follow the principle of least privilege: only grant the permissions your integration needs.

<Warning>
  API key permissions **cannot be modified** after creation. If you need different permissions, you must revoke the old key and create a new one with the correct permissions.
</Warning>

## Permission Scopes

### generate

Allows creating video ad generation jobs.

<ParamField path="generate" type="permission">
  **Grants access to:**

  * `POST /api/v1/generate` - Create new video generation jobs

  **Required for:**

  * Video generation integrations
  * Automation workflows that create ads
  * Bulk video creation tools
</ParamField>

<CodeGroup>
  ```bash Example Request theme={null}
  curl -X POST https://app.nouvel.ai/api/v1/generate \
    -H "Authorization: Bearer nvl_..." \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com/product"],
      "variantCount": 1
    }'
  ```
</CodeGroup>

**Without this permission:**

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

### projects:read

Allows viewing project status, details, and listing projects.

<ParamField path="projects:read" type="permission">
  **Grants access to:**

  * `GET /api/v1/jobs/:id` - Get job status and details
  * `GET /api/v1/projects/:id` - Get project details
  * `GET /api/v1/projects` - List all projects with pagination

  **Required for:**

  * Status polling integrations
  * Dashboard displays
  * Monitoring and reporting tools
</ParamField>

<CodeGroup>
  ```bash Poll Job Status theme={null}
  curl https://app.nouvel.ai/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer nvl_..."
  ```

  ```bash List Projects theme={null}
  curl https://app.nouvel.ai/api/v1/projects?limit=20&offset=0 \
    -H "Authorization: Bearer nvl_..."
  ```
</CodeGroup>

**Without this permission:**

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

### publish

Allows publishing completed video projects to social media platforms.

<ParamField path="publish" type="permission">
  **Grants access to:**

  * `POST /api/v1/publish` - Publish or schedule posts to social platforms
  * `GET /api/v1/publish/:postId` - Check publish status

  **Required for:**

  * Social media automation tools
  * Multi-platform publishing integrations
  * Scheduled content calendars
</ParamField>

<CodeGroup>
  ```bash Publish a Video theme={null}
  curl -X POST https://app.nouvel.ai/api/v1/publish \
    -H "Authorization: Bearer nvl_..." \
    -H "Content-Type: application/json" \
    -d '{
      "projectId": "uuid",
      "platforms": [
        { "platform": "instagram", "accountId": "acct_id", "caption": "Check this out!" }
      ]
    }'
  ```
</CodeGroup>

**Without this permission:**

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

### analytics:read

Allows viewing analytics data for connected social media accounts and published posts.

<ParamField path="analytics:read" type="permission">
  **Grants access to:**

  * `GET /api/v1/accounts` - List connected social media accounts
  * `GET /api/v1/analytics` - Get post-level analytics
  * `GET /api/v1/analytics/daily` - Get daily aggregated metrics
  * `GET /api/v1/analytics/followers` - Get follower growth data

  **Required for:**

  * Analytics dashboards
  * Performance reporting tools
  * ROI tracking integrations
</ParamField>

<CodeGroup>
  ```bash List Connected Accounts theme={null}
  curl https://app.nouvel.ai/api/v1/accounts \
    -H "Authorization: Bearer nvl_..."
  ```

  ```bash Get Post Analytics theme={null}
  curl "https://app.nouvel.ai/api/v1/analytics?platform=instagram&limit=20" \
    -H "Authorization: Bearer nvl_..."
  ```
</CodeGroup>

**Without this permission:**

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

### copilot:chat

Allows using the AI copilot for product research, ad strategy, and creative ideation.

<ParamField path="copilot:chat" type="permission">
  **Grants access to:**

  * `POST /api/v1/copilot/chat` - Send messages to AI copilot

  **Required for:**

  * AI-assisted content planning tools
  * Product research automation
  * Creative brief generation
</ParamField>

<CodeGroup>
  ```bash Chat with Copilot theme={null}
  curl -X POST https://app.nouvel.ai/api/v1/copilot/chat \
    -H "Authorization: Bearer nvl_..." \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        { "role": "user", "content": "Write me a caption for my protein powder" }
      ]
    }'
  ```
</CodeGroup>

**Without this permission:**

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

## Creating API Keys with Permissions

When creating an API key in the dashboard, you select which permissions to grant:

<CodeGroup>
  ```bash Dashboard Flow theme={null}
  1. Navigate to Settings → API Keys
  2. Click "Create API Key"
  3. Enter a name (e.g., "Video Generator Bot")
  4. Select permissions:
     ☑ generate
     ☑ projects:read
     ☐ publish
     ☐ analytics:read
     ☐ copilot:chat
  5. Click "Create"
  6. Copy your key (shown only once)
  ```
</CodeGroup>

<Warning>
  Your API key is shown **only once** during creation. Store it securely in your environment variables or secrets manager. If you lose it, you must revoke and create a new key.
</Warning>

## Common Permission Combinations

Choose a permission set based on your use case:

### Video Generation Bot

**Use case:** Automated video creation without human monitoring

**Permissions:**

* `generate` - Create video generation jobs
* `projects:read` - Poll for completion status

<CodeGroup>
  ```typescript TypeScript Example theme={null}
  // Create job
  const job = await fetch('https://app.nouvel.ai/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer nvl_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ urls: [productUrl] })
  }).then(r => r.json());

  // Poll until complete
  let status = 'generating';
  while (status !== 'completed') {
    const update = await fetch(`https://app.nouvel.ai/api/v1/jobs/${job.jobId}`, {
      headers: { 'Authorization': 'Bearer nvl_...' }
    }).then(r => r.json());

    status = update.status;
    await new Promise(resolve => setTimeout(resolve, 15000));
  }
  ```
</CodeGroup>

### Dashboard Integration

**Use case:** Display project status and analytics in a custom dashboard

**Permissions:**

* `projects:read` - List and view project details
* `analytics:read` - View performance metrics

<CodeGroup>
  ```typescript TypeScript Example theme={null}
  // List recent projects
  const projects = await fetch('https://app.nouvel.ai/api/v1/projects?limit=10', {
    headers: { 'Authorization': 'Bearer nvl_...' }
  }).then(r => r.json());

  // Display in UI
  projects.data.forEach(project => {
    console.log(`${project.product_name}: ${project.status}`);
  });
  ```
</CodeGroup>

### Full Access Integration

**Use case:** Complete integration with all Nouvel features

**Permissions:**

* `generate` - Create videos
* `projects:read` - Monitor projects
* `publish` - Publish to social platforms
* `analytics:read` - View performance data
* `copilot:chat` - AI assistance

<Note>
  Most integrations only need `generate` + `projects:read`. Only grant additional permissions if you're actively using those features.
</Note>

### Read-Only Access

**Use case:** Monitoring and reporting without creating new content

**Permissions:**

* `projects:read` - View project status
* `analytics:read` - View metrics
  Perfect for:
* Reporting dashboards
* Project management tools
* Client portals

## Principle of Least Privilege

<Tip>
  **Always follow the principle of least privilege**: only grant the minimum permissions required for your integration to function.
</Tip>

**Why this matters:**

1. **Security** - If an API key is compromised, damage is limited to granted permissions
2. **Clarity** - Permissions make it clear what each integration can do
3. **Compliance** - Easier to audit access and maintain security standards
4. **Cost control** - Keys without `generate` permission can't consume quota

## Examples by Use Case

### E-commerce Automation

You're building a Shopify app that auto-generates videos when products are added:

**Recommended permissions:**

* ✅ `generate` - Create videos for new products
* ✅ `projects:read` - Check generation status
* ❌ `publish` - Not needed if you're not auto-publishing
* ❌ `analytics:read` - Not needed for automation
* ❌ `copilot:chat` - Not needed for automation

### Marketing Dashboard

You're building a dashboard for clients to view their video performance:

**Recommended permissions:**

* ❌ `generate` - Clients shouldn't create videos via this dashboard
* ✅ `projects:read` - Display project status
* ✅ `analytics:read` - Show performance metrics - ❌ `publish` - Not displaying social features
* ❌ `copilot:chat` - Not exposing AI features

### Content Calendar Tool

You're building a tool to generate and schedule social content:

**Recommended permissions:**

* ✅ `generate` - Create videos
* ✅ `projects:read` - Monitor generation
* ✅ `publish` - Schedule to social platforms - ✅ `analytics:read` - Track post performance - ✅ `copilot:chat` - Help users ideate content

### Internal Reporting Script

You're writing a script to export project data for internal reporting:

**Recommended permissions:**

* ❌ `generate` - Script only reads data
* ✅ `projects:read` - Export project details
* ✅ `analytics:read` - Export metrics - ❌ `publish` - Script doesn't publish
* ❌ `copilot:chat` - Script doesn't use AI

## Managing API Keys

### Rotating Keys

To rotate an API key:

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Test that the new key works in production
4. Revoke the old key

<Warning>
  Always test the new key before revoking the old one to avoid service disruption.
</Warning>

### Revoking Keys

Revoke keys immediately if:

* The key is compromised or leaked
* The integration is no longer in use
* You need to change permissions (create new key with different permissions)

<CodeGroup>
  ```bash Revoke via Dashboard theme={null}
  1. Navigate to Settings → API Keys
  2. Find the key to revoke
  3. Click the "..." menu
  4. Select "Revoke"
  5. Confirm the action
  ```
</CodeGroup>

**After revocation:**

* All requests with that key return `401 Unauthorized`
* The key cannot be recovered (create a new key if needed)
* Revocation is immediate (no grace period)

## Security Best Practices

### 1. Store Keys Securely

**Never** hardcode API keys in your source code. Use environment variables or secrets managers:

<CodeGroup>
  ```typescript TypeScript (.env) theme={null}
  # .env (never commit to git)
  NOUVEL_API_KEY=nvl_your_key_here
  ```

  ```typescript TypeScript (usage) theme={null}
  const apiKey = process.env.NOUVEL_API_KEY;

  const response = await fetch('https://app.nouvel.ai/api/v1/generate', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  ```
</CodeGroup>

### 2. Use Separate Keys per Environment

Create different API keys for development, staging, and production:

* `Video Gen - Production` (full permissions)
* `Video Gen - Staging` (full permissions)
* `Video Gen - Development` (limited permissions)

This prevents dev environments from affecting production quota.

### 3. Monitor Key Usage

Track which keys are making requests:

* Name keys descriptively (`Shopify App Prod`, `Dashboard`, `Reporting Script`)
* Review key activity regularly in the dashboard
* Revoke unused keys

### 4. Limit Key Distribution

* Don't share keys across multiple applications
* Create separate keys for each integration
* Limit access to keys within your team (only developers who need them)

## Checking Permissions

If you receive a 403 Forbidden error, your key lacks the required permission. Check your key's permissions in the dashboard:

<CodeGroup>
  ```bash Check Permissions theme={null}
  1. Navigate to Settings → API Keys
  2. Find your key in the list
  3. View the "Permissions" column
  4. If needed, create a new key with the correct permissions
  ```
</CodeGroup>

## Questions?

Need help choosing the right permissions for your use case? Contact us at [support@nouvel.ai](mailto:support@nouvel.ai).