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 customer-facing API 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. API key management requires an org-wide key.

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 protocol connections use MCP-specific credentials, not customer API keys.

• MCP OAuth tokens are prefixed with mcpo_. OAuth is the default for new MCP servers; clients sign in through Weavz and receive a token scoped to the MCP server, workspace, and end user.
• End-user MCP bearer tokens are prefixed with mcp_. API and SDK customers can create them for bearer-enabled MCP servers; each token is scoped to one MCP server, workspace, and end user.
• Static MCP bearer tokens are also prefixed with mcp_. These shared server credentials are returned only when an MCP server's authMode is bearer or oauth_and_bearer and the workspace can safely use service-style access.

See the MCP Servers documentation for auth modes, end-user access policy, and programmatic bearer or OAuth token issuance.

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.