Permissions

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.

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.

Permission Scopes

generate

Allows creating video ad generation jobs.

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

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
  }'

Without this permission:

{
  "error": "This API key does not have the 'generate' permission"
}

projects:read

Allows viewing project status, details, and listing projects.

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

curl https://app.nouvel.ai/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer nvl_..."

curl https://app.nouvel.ai/api/v1/projects?limit=20&offset=0 \
  -H "Authorization: Bearer nvl_..."

Without this permission:

{
  "error": "This API key does not have the 'projects:read' permission"
}

publish

Allows publishing completed video projects to social media platforms.

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

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!" }
    ]
  }'

Without this permission:

{
  "error": "This API key does not have the 'publish' permission"
}

analytics:read

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

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

curl https://app.nouvel.ai/api/v1/accounts \
  -H "Authorization: Bearer nvl_..."

curl "https://app.nouvel.ai/api/v1/analytics?platform=instagram&limit=20" \
  -H "Authorization: Bearer nvl_..."

Without this permission:

{
  "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.

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

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" }
    ]
  }'

Without this permission:

{
  "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:

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)

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.

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

// 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));
}

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

// 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}`);
});

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

Most integrations only need generate + projects:read. Only grant additional permissions if you’re actively using those features.

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

Always follow the principle of least privilege: only grant the minimum permissions required for your integration to function.

Why this matters:

Security - If an API key is compromised, damage is limited to granted permissions
Clarity - Permissions make it clear what each integration can do
Compliance - Easier to audit access and maintain security standards
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:

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

Always test the new key before revoking the old one to avoid service disruption.

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)

Navigate to Settings → API Keys
Find the key to revoke
Click the "..." menu
Select "Revoke"
Confirm the action

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:

# .env (never commit to git)
NOUVEL_API_KEY=nvl_your_key_here

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'
  }
});

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:

Navigate to Settings → API Keys
Find your key in the list
View the "Permissions" column
If needed, create a new key with the correct permissions

Questions?

Need help choosing the right permissions for your use case? Contact us at support@nouvel.ai.

Getting Started

Core Concepts

Video Generation

Projects

Publishing

Analytics

AI Copilot

Overview

Permission Scopes

generate

projects:read

publish

analytics:read

copilot:chat

Creating API Keys with Permissions

Common Permission Combinations

Video Generation Bot

Dashboard Integration

Full Access Integration

Read-Only Access

Principle of Least Privilege

Examples by Use Case

E-commerce Automation

Marketing Dashboard

Content Calendar Tool

Internal Reporting Script

Managing API Keys

Rotating Keys

Revoking Keys

Security Best Practices

1. Store Keys Securely

2. Use Separate Keys per Environment

3. Monitor Key Usage

4. Limit Key Distribution

Checking Permissions

Questions?

​Overview

​Permission Scopes

​generate

​projects:read

​publish

​analytics:read

​copilot:chat

​Creating API Keys with Permissions

​Common Permission Combinations

​Video Generation Bot

​Dashboard Integration

​Full Access Integration

​Read-Only Access

​Principle of Least Privilege

​Examples by Use Case

​E-commerce Automation

​Marketing Dashboard

​Content Calendar Tool

​Internal Reporting Script

​Managing API Keys

​Rotating Keys

​Revoking Keys

​Security Best Practices

​1. Store Keys Securely

​2. Use Separate Keys per Environment

​3. Monitor Key Usage

​4. Limit Key Distribution

​Checking Permissions

​Questions?

Overview

Permission Scopes

generate

projects:read

publish

analytics:read

copilot:chat

Creating API Keys with Permissions

Common Permission Combinations

Video Generation Bot

Dashboard Integration

Full Access Integration

Read-Only Access

Principle of Least Privilege

Examples by Use Case

E-commerce Automation

Marketing Dashboard

Content Calendar Tool

Internal Reporting Script

Managing API Keys

Rotating Keys

Revoking Keys

Security Best Practices

1. Store Keys Securely

2. Use Separate Keys per Environment

3. Monitor Key Usage

4. Limit Key Distribution

Checking Permissions

Questions?