Authentication

Every request to the Weavz API must be authenticated. The only exception is the BetterAuth endpoints under /api/auth/*, which handle sign-up, sign-in, and session management.

Weavz supports four authentication methods, each designed for a different use case. Choose the method that fits your integration scenario.

1. Session (Dashboard)

Cookie-based sessions powered by BetterAuth. This is the default method used by the Weavz dashboard and any browser-based client.

How it works

• The user signs in via email + password or a social provider (Google, GitHub, Discord).
• BetterAuth sets an HTTP-only session cookie on the response.
• Subsequent requests from the browser automatically include the cookie.
• The API validates the cookie against the sessions table in the database and resolves the active organization from the session record.

Example: Sign in

curl -X POST https://your-api.example.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }' \
  -c cookies.txt

Example: Use session cookie

curl https://your-api.example.com/api/v1/connections \
  -b cookies.txt

Session authentication is only recommended for browser-based clients. For server-to-server integrations, use API keys instead.

2. API Key

API keys are long-lived tokens scoped to a single organization. They are the recommended method for SaaS customers calling the REST API from their own backend or scripts.

How it works

• Create an API key in the Weavz dashboard under Settings → API Keys.
• All API keys are prefixed with wvz_ for easy identification.
• Include the key in the Authorization header as a Bearer token.
• The key is hashed and looked up in the api_keys table. The associated organization is used for all authorization checks.

Example

curl https://your-api.example.com/api/v1/connections \
  -H "Authorization: Bearer wvz_abc123def456ghi789"

Security notes

• API keys grant full access to all resources within the organization. Treat them like passwords.
• Never expose API keys in client-side code or public repositories.
• Rotate keys periodically. You can revoke a key at any time from the dashboard.

3. Service Key (Enterprise)

Service keys provide admin-level access for backend-to-backend communication, allowing a trusted service to operate on behalf of any organization. Service keys are available on Enterprise plans.

Contact sales to learn more about service key authentication for your use case.

4. MCP Bearer Token

MCP bearer tokens authenticate MCP protocol clients (such as Claude Desktop, Cursor, or other AI agents) connecting to a Weavz MCP server endpoint.

How it works

• Each MCP server has a unique bearer token, generated when the server is created. The token is prefixed with mcp_.
• The MCP client includes this token in the Authorization header when connecting to the server's SSE endpoint.
• The token is looked up in the mcp_servers table, and the request is scoped to the server's organization and project.

Example: Connect to MCP server

curl https://your-api.example.com/mcp/server_abc123 \
  -H "Authorization: Bearer mcp_token_xyz789" \
  -H "Accept: text/event-stream"

MCP client configuration

When configuring an MCP client (e.g., Claude Desktop), provide the server URL and token:

{
  "mcpServers": {
    "weavz": {
      "url": "https://your-api.example.com/mcp/server_abc123",
      "headers": {
        "Authorization": "Bearer mcp_token_xyz789"
      }
    }
  }
}

Error Responses

When authentication fails, the API returns one of the following error responses:

// 401 Unauthorized — missing or invalid credentials
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing authentication credentials"
}

// 403 Forbidden — valid credentials, insufficient permissions
{
  "error": "FORBIDDEN",
  "message": "You do not have access to this resource"
}

Summary