API Keys

Create and manage API keys for programmatic access.

API Keys

API keys provide programmatic access to the Weavz API. Keys are scoped to an organization and prefixed with wvz_.

List API Keys

GET/api/v1/api-keys

List all API keys for your organization. Key values are masked — only the keyPrefix (first 8 characters) is shown.

Response

json

{
  "apiKeys": [
    {
      "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Key",
      "keyPrefix": "wvz_ab12",
      "permissions": null,
      "lastUsedAt": "2025-01-16T08:00:00.000Z",
      "expiresAt": null,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Example

bash

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

typescript

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

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.api_keys.list()
api_keys = result["apiKeys"]

typescript

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

python

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

Create API Key

POST/api/v1/api-keys

Create a new API key. The full key value is returned only once in the plainKey field — store it securely.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Descriptive name for the key
`expiresAt`	string (date-time)	No	Expiration timestamp (no expiry if omitted)
`permissions`	object	No	Permission scope (unrestricted if omitted). See below.

Permissions Object

Field	Type	Required	Description
`scope`	string	Yes	`"org"` for full access, `"workspace"` for workspace-scoped
`workspaceIds`	string[]	When scope is `"workspace"`	UUIDs of the workspaces this key can access

Response (201)

json

{
  "apiKey": {
    "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Key",
    "keyPrefix": "wvz_ab12",
    "permissions": null,
    "lastUsedAt": null,
    "expiresAt": null,
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "plainKey": "wvz_ab12cd34ef56gh78ij90kl12mn34op56"
}

Example

bash

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"}'

typescript

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

python

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

typescript

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()

python

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()

Create a workspace-scoped key:

bash

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": "Workspace-Only Key",
    "permissions": {
      "scope": "workspace",
      "workspaceIds": ["PROJECT_UUID_1", "PROJECT_UUID_2"]
    }
  }'

typescript

const { apiKey, plainKey } = await client.apiKeys.create({
  name: 'Workspace-Only Key',
  permissions: {
    scope: 'workspace',
    workspaceIds: ['PROJECT_UUID_1', 'PROJECT_UUID_2'],
  },
})

python

result = client.api_keys.create(
    name="Workspace-Only Key",
    scope="workspace",
    workspace_ids=["PROJECT_UUID_1", "PROJECT_UUID_2"],
)

typescript

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: 'Workspace-Only Key',
    permissions: {
      scope: 'workspace',
      workspaceIds: ['PROJECT_UUID_1', 'PROJECT_UUID_2'],
    },
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/api-keys",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "name": "Workspace-Only Key",
        "permissions": {
            "scope": "workspace",
            "workspaceIds": ["PROJECT_UUID_1", "PROJECT_UUID_2"],
        },
    },
)
data = res.json()

Workspace-scoped keys can only access resources within the specified workspaces. Requests to resources outside the allowed workspaces return 403 SCOPE_DENIED.

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing key name
`403`	`QUOTA_EXCEEDED`	API key limit reached for your plan
`403`	`SCOPE_DENIED`	Workspace-scoped key cannot access this resource

Revoke API Key

DELETE/api/v1/api-keys/:id

Revoke an API key. The key is immediately invalidated and can no longer be used for authentication.

Path Parameters

Field	Type	Description
`id`	string (uuid)	API key ID

Response

json

{
  "deleted": true,
  "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Example

bash

curl -X DELETE https://api.weavz.io/api/v1/api-keys/k1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

await client.apiKeys.delete('k1a2b3c4-d5e6-7890-abcd-ef1234567890')

python

client.api_keys.delete("k1a2b3c4-d5e6-7890-abcd-ef1234567890")

typescript

const res = await fetch('https://api.weavz.io/api/v1/api-keys/k1a2b3c4-d5e6-7890-abcd-ef1234567890', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.delete(
    "https://api.weavz.io/api/v1/api-keys/k1a2b3c4-d5e6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	API key not found