Authentication

All API requests require authentication via an API key passed as a Bearer token in the Authorization header.

API Key Authentication

Include your API key in every request:

curl https://api.weavz.io/api/v1/workspaces \
  -H "Authorization: Bearer wvz_your_api_key"

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { workspaces } = await client.workspaces.list()

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.workspaces.list()

const res = await fetch('https://api.weavz.io/api/v1/workspaces', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/workspaces",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

API keys are scoped to an organization. All resources accessed through the key belong to that organization.

Org-Wide vs Workspace-Scoped Keys

By default, API keys have org-wide access — they can read and modify all resources across the organization. For least-privilege access, you can create workspace-scoped keys that are restricted to specific workspaces. Workspace-scoped keys can only interact with resources (connections, MCP servers, triggers, actions) belonging to their allowed workspaces. Requests that target resources outside the permitted workspaces return a 403 error with code SCOPE_DENIED. Org-level administration endpoints (managing API keys, org settings, billing) also require org-wide keys.

See API Keys for details on the permissions field.

Key Format

API keys are prefixed with wvz_ for easy identification. When you create a key, the full key value is returned only once — store it securely.

Creating API Keys

Create keys via the dashboard under Settings > API Keys, or programmatically through the API Keys endpoint.

curl -X POST https://api.weavz.io/api/v1/api-keys \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

const { apiKey, plainKey } = await client.apiKeys.create({
  name: 'Production Key',
})

result = client.api_keys.create(name="Production Key")

const res = await fetch('https://api.weavz.io/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Production Key' }),
})
const data = await res.json()

res = httpx.post(
    "https://api.weavz.io/api/v1/api-keys",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"name": "Production Key"},
)
data = res.json()

The response includes a plainKey field with the full key — this is the only time it will be visible.

Rate Limiting

API requests are rate-limited based on your organization's plan tier. Rate limit information is included in every response:

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

Error Responses

All errors follow a consistent format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common Error Codes

MCP Server Tokens

MCP servers use separate bearer tokens (prefixed with mcp_) for MCP protocol connections. These tokens are generated when you create an MCP server and can be regenerated at any time. See the MCP Servers documentation for details.

Base URL

All API endpoints use the following base URL:

https://api.weavz.io

For enterprise on-premise deployments, contact sales for your dedicated URL.