API Authentication

The Zenovay API authenticates with API credentials. All API requests must include a valid credential.

Personal tokens and workspace keys

Zenovay has two kinds of API credentials. Both authenticate the same way (see below); they differ in who owns them and how long they live.

Personal API tokens act on your behalf across the teams you belong to. Create them in Account > API tokens. They carry your own access, can be scoped (see Scopes), and are revoked automatically when you leave a team. Use them for your own scripts, the CLI, or local development.

Workspace API keys belong to a workspace, not a person. Owners and admins create and manage them in Settings > API keys. They survive member changes, so they are the right choice for shared integrations and CI. A workspace key can have full access or be scoped to a single website.

Getting Your API Key

1. Log in to your Zenovay dashboard
2. Navigate to Settings > API Keys
3. Click Create New API Key
4. Give your key a descriptive name
5. Copy the generated key (it will only be shown once)

Using API Keys

Include your API key in the X-API-Key header of every request:

curl -X GET "https://api.zenovay.com/api/external/v1/websites" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"

Bearer Token Authentication

As an alternative to the X-API-Key header, you can authenticate using the standard Authorization: Bearer header:

curl -X GET "https://api.zenovay.com/api/external/v1/websites" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

Both methods use the same API key. Choose whichever fits your application or HTTP client best.

JavaScript Example

const apiKey = process.env.ZENOVAY_API_KEY;

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
headers: {
  'X-API-Key': apiKey,
  'Content-Type': 'application/json'
}
});

const data = await response.json();

Scopes

Credentials can carry different permission levels:

full_access - The default. Everything the credential owner can do
read - View analytics data and website configuration
write - Modify website settings and configuration
admin - Elevated access including management actions

For personal tokens, the admin scope is only granted for teams where you are already an owner or admin. A token that covers a team where you are not an admin cannot be minted with the admin scope.

Rate Limiting

Security Best Practices

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys regularly
• Create separate keys for different environments (dev, staging, prod)
• Delete unused keys immediately

Common Errors