Auth

Vectora’s authentication layer ensures that only authorized users and services can access resources, namespaces, and sensitive operations. This section documents the identity mechanisms, API key management, and access control that protect your context infrastructure.

Authentication and Authorization in Vectora

Topics in this section

Typical Authentication Flow

    graph LR
    A[User / Service] --> B{Access Type}
    B -->|Human| C[Login via SSO]
    B -->|Machine| D[API Key with scope]

    C --> E[JWT with claims: userId, roles, namespaces]
    D --> F[Key validation + rate limiting]

    E --> G[RBAC Middleware]
    F --> G

    G --> H{Permission granted?}
    H -->|Yes| I[Execute operation]
    H -->|No| J[Return 403 Forbidden]
  

Fundamental Concepts

Security Best Practices

Use scoped API Keys: Grant only search or read if the integration doesn’t need to write. Rotate keys periodically: Renew API Keys every 90 days or after any security incident. Validate namespaces in every call: Don’t just trust the token; revalidate scope at runtime. Monitor audit logs: Use audit_logs to detect anomalous access patterns. Never expose keys in the client: API Keys belong to the backend or the principal agent, never the browser.

Integration with Your System

Example: JWT Validation in your backend

// Example: JWT validation middleware
import { verifyJWT } from "@vectora/auth";

export async function authMiddleware(req: Request, next: Handler) {
  const token = req.headers.get("Authorization")?.replace("Bearer ", "");
  if (!token) return next({ status: 401, error: "Missing token" });

  try {
    const claims = await verifyJWT(token, { audience: "vectora-api" });
    req.context = {
      userId: claims.sub,
      roles: claims.roles,
      namespaces: claims.namespaces,
    };
    return next();
  } catch {
    return next({ status: 403, error: "Invalid token" });
  }
}

Example: Using an API Key in an MCP call

{
  "mcpServers": {
    "vectora": {
      "command": "npx",
      "args": ["@kaffyn/vectora", "mcp-serve"],
      "env": {
        "VECTORA_API_KEY": "vca_live_...",
        "VECTORA_NAMESPACE": "my-project"
      }
    }
  }
}

Frequently Asked Questions

Q: Do I need SSO to use Vectora? A: No. The Free plan uses local authentication via vectora auth login. SSO is available on Pro/Team plans for integration with corporate providers.

Q: Can I use my own auth infrastructure? A: Yes. Vectora accepts any valid JWT configured via auth.jwt.publicKey. Consult SSO for custom integration details.

Q: How do I revoke a compromised API Key? A: Via the dashboard (/settings/api-keys) or CLI: vectora api-key revoke --id <key_id>. Revocation is immediate across all nodes.

Q: Does Vectora store my credentials? A: No. API Keys are stored as hashes (bcrypt). JWT tokens are validated but not persisted. Provider credentials (Gemini, Voyage) are provided via BYOK and never touched by Kaffyn.

External Linking

Phrase to remember: “Authentication verifies who you are. Authorization defines what you can do. Vectora enforces both on every tool call — not just at login.”

Part of the Vectora ecosystem · Open Source (MIT) · Contributors