Authentication

The Envizion AI API supports three authentication methods. API key authentication is recommended for most integrations.

Authentication Methods

API Key

Recommended

Pass your API key via the X-API-Key header. Keys are scoped, rate-limited, and can be rotated without downtime.

JWT Bearer Token

Pass a JWT token via Authorization: Bearer <token>. Used by the frontend and internal services. Tokens include user ID, tier, and scopes.

Internal Auth

Service-to-service authentication via X-Internal-Auth header. Grants admin-level access. Not for external use.

Using API Keys

API keys start with the prefix vk_ and are 51+ characters long. Pass the key in the X-API-Key header with every request.

cURL

curl -s https://api.envizion.ai/v1/agents \
  -H "X-API-Key: vk_your_api_key_here"

Python

import httpx

resp = httpx.get(
    "https://api.envizion.ai/v1/agents",
    headers={"X-API-Key": "vk_your_api_key_here"}
)
print(resp.json())

TypeScript

const resp = await fetch("https://api.envizion.ai/v1/agents", {
  headers: { "X-API-Key": "vk_your_api_key_here" }
});
const data = await resp.json();
console.log(data);

Creating API Keys

Create keys from your dashboard or programmatically via the API. You can create up to 10 active keys per account. The full key is only returned once at creation time -- store it securely.

Create a key via API

curl -s -X POST https://api.envizion.ai/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "scopes": ["read", "write"],
    "expires_in_days": 90
  }'

Response

{
  "id": "123",
  "name": "Production Key",
  "key": "vk_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "key_prefix": "vk_aBcDeFgH",
  "scopes": ["read", "write"],
  "rate_limit_tier": "starter",
  "is_active": true,
  "expires_at": "2026-05-13T00:00:00Z",
  "created_at": "2026-02-12T12:00:00Z"
}

Important

The key field is only returned when the key is first created. After that, only the key_prefix is available for identification. Store your key in a secure location (e.g., environment variable, secret manager).

Scopes

Each API key is assigned one or more scopes that control what operations it can perform. Request only the scopes you need for your integration.

Scope	Description	Covers
`read`	Read-only access to resources	GET, HEAD, OPTIONS
`write`	Create, update, and delete resources. Implies read.	GET, POST, PUT, PATCH, DELETE
`billing`	Access billing and payment endpoints	Stripe checkout, top-up
`publish`	Publish content to external platforms	POST /v1/publish/*
`admin`	Full access to all endpoints. Bypasses all scope checks.	All methods, all paths

Scope hierarchy

write implies read. admin implies all scopes. The billing and publish scopes are independent and must be explicitly granted.

Scope Matrix

Which scopes are required for each endpoint:

Endpoint	read	write	billing	publish	admin
GET /v1/agents	✓	✓	-	-	✓
POST /v1/agents	-	✓	-	-	✓
DELETE /v1/agents/:id	-	✓	-	-	✓
POST /v1/runs	-	✓	-	-	✓
GET /v1/runs/:id	✓	✓	-	-	✓
GET /v1/runs/:id/stream	✓	✓	-	-	✓
GET /v1/tools	✓	✓	-	-	✓
GET /v1/marketplace/*	✓	✓	-	-	✓
POST /v1/marketplace/*/install	-	✓	-	-	✓
GET /v1/credits/wallet	✓	✓	-	-	✓
POST /v1/credits/stripe/*	-	-	✓	-	✓
POST /v1/publish/*	-	-	-	✓	✓
GET /v1/downloads/*	✓	✓	-	-	✓
POST /v1/webhooks	-	✓	-	-	✓
GET /v1/webhooks	✓	✓	-	-	✓
GET /v1/usage/*	✓	✓	-	-	✓

Key Rotation

Rotate a key to generate a new secret while preserving its name, scopes, and configuration. The old key is immediately revoked.

Rotate a key

curl -s -X POST https://api.envizion.ai/api-keys/{key_id}/rotate \
  -H "X-API-Key: vk_your_current_key"

Rotation workflow

Call the rotate endpoint with the old key
Receive the new key in the response (returned only once)
Update your application with the new key
The old key is immediately and permanently revoked

Key Expiration

Keys can optionally have an expiration date set at creation time via the expires_in_days parameter. When a key expires, the API returns a 401 with error code api_key_expired.

// Expired key response
{
  "error": "api_key_expired",
  "detail": "API key has expired. Rotate or create a new key."
}

When you receive this error, create a new key or rotate the expired one. If no expires_in_days is provided, the key does not expire.

Security Best Practices

Use the minimum required scopes

Only grant the scopes your integration needs. A read-only dashboard should use the read scope, not write.

Never expose keys in client-side code

API keys should only be used server-side. Never embed them in frontend JavaScript, mobile apps, or public repositories.

Set expiration dates

Use expires_in_days to automatically expire keys. 90 days is a good default for production keys.

Rotate keys regularly

Use the rotate endpoint to periodically refresh keys without changing configuration. Rotate immediately if a key is compromised.

Use environment variables

Store keys in environment variables or a secret manager (e.g., AWS Secrets Manager, Vault). Never hardcode them.

Monitor usage

Check the /v1/usage/by-key endpoint to detect unusual activity patterns that might indicate a compromised key.

→Endpoint Reference →Rate Limits