Authentication & API Keys

Pro Plan

Secure your API access with API keys. Create, manage, and rotate keys for your integrations.

Authentication Methods

API Keys (Primary)

Authenticate using the X-API-Key header (recommended) or the Authorization: Bearer header:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Or using Bearer authentication:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

API keys always start with the zv_ prefix.

Creating API Keys

Step 1: Access API Settings

1. Go to API Keys in the sidebar
2. Click "Create New Key"
3. Click "Create New Key"

Step 2: Configure Key

┌─────────────────────────────────────────────────────┐
│ Create API Key                                      │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Name:                                               │
│ [Production Integration                   ]        │
│                                                     │
│ Description (optional):                             │
│ [Main production API access              ]         │
│                                                     │
│ Permissions:                                        │
│ ☑ Read analytics data                              │
│ ☑ Track events                                     │
│ ☐ Manage websites                                  │
│ ☐ Manage team                                      │
│ ☐ Admin access                                     │
│                                                     │
│ Website Access:                                     │
│ ● All websites                                     │
│ ○ Selected websites only                           │
│                                                     │
│ Expiration:                                         │
│ ○ Never                                            │
│ ● 1 year                                           │
│ ○ Custom date                                      │
│                                                     │
│ [Cancel] [Create Key]                              │
└─────────────────────────────────────────────────────┘

Step 3: Save Your Key

Important: The key is only shown once!

┌─────────────────────────────────────────────────────┐
│ API Key Created                                     │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ ⚠️ Copy this key now - it won't be shown again!    │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [Copy to Clipboard]                                │
│                                                     │
└─────────────────────────────────────────────────────┘

Key Format

All API keys use a single format:

• Prefix: zv_
• Keys are stored as SHA-256 hashes for security
• The full key is only shown once at creation time

There is no separate test/sandbox key type. Use separate API keys for development and production by creating multiple keys with descriptive names.

Key Permissions

API keys provide access to the External API endpoints. The key is scoped to the websites you have access to through your organization.

What API Keys Can Access

Endpoint Category	Endpoints
Analytics	GET /analytics/:websiteId (overview, visitors, pages, countries, technology)
Websites	GET /websites, GET /websites/:websiteId
Heatmaps	GET /heatmaps/:websiteId/pages
Session Replays	GET /replays/:websiteId/sessions
Error Groups	GET /errors/:websiteId/groups
Usage	GET /usage

Website Restrictions

All Websites

Key works with all team websites:

• Simplest setup
• Access all data
• Good for internal tools

Selected Websites

Limit to specific websites:

1. Choose "Selected websites"
2. Check allowed websites
3. Key only works for those

Use Cases for Restrictions

Scenario	Restriction
Client-specific key	One website
Department key	Department websites
Partner access	Shared websites only

Key Expiration

Expiration Options

Option	Use Case
Never	Long-term integrations
1 year	Standard practice
90 days	Higher security
Custom	Specific needs

Expiration Handling

When a key expires:

• API returns 401 Unauthorized
• Must create new key
• Update integrations

Expiration Warnings

Receive warnings at:

• 30 days before
• 7 days before
• 1 day before

Managing Keys

View All Keys

┌─────────────────────────────────────────────────────┐
│ API Keys                              [+ Create]   │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Name             Prefix   Created      Last Used   │
│ ─────────────────────────────────────────────────── │
│ Production       zv_      Jan 2025     2 min ago   │
│ Dashboard        zv_      Feb 2025     1 hour ago  │
│ Dev Testing      zv_      Mar 2025     5 days ago  │
│                                                     │
└─────────────────────────────────────────────────────┘

Key Details

Click a key to see:

• Full permissions
• Website access
• Usage statistics
• Last used timestamp

Regenerate Key

If key is compromised:

1. Click key name
2. Click "Regenerate"
3. Confirm action
4. New key generated
5. Old key invalidated

Delete Key

Remove unused keys:

1. Click key name
2. Click "Delete"
3. Confirm deletion
4. Key immediately invalid

Key Security

Best Practices

Practice	Why
Use environment variables	Don't hardcode
Minimal permissions	Limit blast radius
Regular rotation	Reduce exposure
Separate per environment	Isolate dev/prod
Monitor usage	Detect anomalies

Environment Variables

Store keys securely:

# .env file (never commit!)
ZENOVAY_API_KEY=zv_abc123...

// Use in code
const apiKey = process.env.ZENOVAY_API_KEY;

Key Rotation

Rotate keys periodically:

1. Create new key
2. Update applications
3. Verify working
4. Delete old key

Using API Keys

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

Troubleshooting

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid"
  }
}

Check:

• Key copied correctly
• No extra spaces
• Key not deleted/expired

Insufficient Permissions

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have permission for this action"
  }
}

Check:

• Required permission enabled
• Website access allowed
• Key not read-only

Key Expired

{
  "error": {
    "code": "key_expired",
    "message": "This API key has expired"
  }
}

Solution:

• Create new key
• Update application
• Consider longer expiration

Audit Logging

Key Usage Logged

All API access is logged:

• Timestamp
• Endpoint accessed
• Response status
• IP address

View Key Logs

1. Click key name
2. View "Usage Logs"
3. Filter by date/endpoint

Next Steps

• API Overview
• REST API Reference
• Rate Limits