Authentication & Access Control

// Your backend (e.g. a Next.js route). Runs with your API key, never in the browser or agent.
import { SwarmV } from "@swarmv/sdk";

const swarmv = new SwarmV(); // SWARMV_API_KEY from the environment

export async function POST(req: Request) {
  const user = await getSignedInUser(req);          // your own auth
  if (!user) return new Response("Unauthorized", { status: 401 });

  const token = await swarmv.generateUserToken(`user:${user.id}`, {
    expiresIn: 900,                                  // seconds, max 3600
    scopes: ["vector:read", "vector:write"],         // optional: narrower than the key
  });
  return Response.json({ token });
}

from swarmv import SwarmV

swarmv = SwarmV()  # SWARMV_API_KEY from the environment

def swarmv_token_for(user_id: str) -> str:
    return swarmv.generate_user_token(f"user:{user_id}", 900, scopes=["vector:read"])

import { SwarmV } from "@swarmv/sdk";

// In the agent / client: no API key. getToken() is called again automatically
// when the token expires, so long-running agents keep working.
const memory = new SwarmV({
  getToken: async () => {
    const res = await fetch("https://your-backend.example.com/swarmv-token", { method: "POST", headers: { Authorization: `Bearer ${session}` } });
    return (await res.json()).token;
  },
});

// Only returns vectors in containers this user can view.
const results = await memory.search(queryEmbedding, { topK: 5 });

// Writes need a container the user can edit.
await memory.insert({ id: "4021", vector: noteEmbedding, metadata: { container_id: "container:apollo" } });
await memory.delete("4021", { containerId: "container:apollo" });

from swarmv import SwarmV

# token_provider is called on first use and whenever the token expires (sync or async).
memory = SwarmV(token_provider=lambda: fetch_token_from_my_backend())

results = memory.search(query_embedding, top_k=5)
memory.delete("4021", container_id="container:apollo")

// Pro and Enterprise. Backend key with graph:admin.
// Many changes at once: sent in batches of 500, each all-or-nothing, safe to retry.
await memory.graph.batch([
  { subject: "user:ana", relation: "member", object: "group:engineering" },
  { subject: "user:bob", relation: "member", object: "group:engineering" },
  { op: "remove", subject: "user:carl", relation: "member", object: "group:engineering" },
]);

// Mirror a list you keep elsewhere (HR system, identity provider), e.g. nightly:
// afterwards group:engineering's members are exactly these.
const preview = await memory.graph.sync(
  { object: "group:engineering", relation: "member", subjects: employeesInEngineering },
  { dryRun: true },
); // { current, would_add, would_remove }
await memory.graph.sync({ object: "group:engineering", relation: "member", subjects: employeesInEngineering });

// Backup or audit: every relationship, page by page.
for await (const edge of memory.graph.exportRelations()) console.log(edge);

swarmv.batch_relations([
    {"subject": "user:ana", "relation": "member", "object": "group:engineering"},
    {"op": "remove", "subject": "user:carl", "relation": "member", "object": "group:engineering"},
])

swarmv.sync_relations("group:engineering", "member", employees_in_engineering, dry_run=True)
swarmv.sync_relations("group:engineering", "member", employees_in_engineering)

for edge in swarmv.export_relations():
    print(edge)